API - Getting Started


The purpose of this article is to explain getting started with using API on ScaleArc v3.2.

  • Abount the Guide
  • Intended Audience
  • Introduction to Scalearc APIs
  • How cURL Commands Work
  • More API Details from the ScaleArc UI and a step-by-step Example


How do I use the ScaleArc API?  


About the Guide

ScaleArc can be configured using an external RESTful API. This edition of Application Programming Interface (API) Quick Start Guide provides information about the most commonly used ScaleArc APIs. The APIs allow a programmatic way of communication between the application(s) and the ScaleArc system to use, configure and monitor ScaleArc. The ScaleArc 3.2 APIs are based on fully RESTful HTTP service that uses all aspects of the HTTP protocol, including methods (e.g., GET, PUT, POST, or DELETE) and URIs. It uses JSON (or JavaScript Object Notation) for serializing the data in request and response formats. This guide describes the various APIs, their request and response parameters and examples on how to use them.

Intended Audience

ScaleArc provides many different APIs for configuring and managing ScaleArc system. This guide provides required information to system administrators who are interested in automating ScaleArc deployment, configuration management and monitoring. The API provides standards based framework that can be easily integrated with their existing infrastructure and services for managing ScaleArc.

This guide also assists software developers who want to develop applications using ScaleArc. The API provides developers the ability of controlling and using the ScaleArc software from their custom applications dynamically. The API allows the developers to easily deploy, configure and use ScaleArc with their applications, in any language and platform they like.

To use this information, you should have access to the ScaleArc software, and you should also be familiar with the following concepts:

  • ScaleArc Software
  • RESTful web services
  • HTTP/1.1
  • JSON data serialization formats

 Introduction to ScaleArc API's

The ScaleArc APIs are based on fully RESTful HTTP service that uses all aspects of the HTTP protocol, including methods (e.g., GET, PUT, POST, or DELETE) and URIs. It uses JSON (or JavaScript Object Notation) for serializing the data in request and response formats.

To use ScaleArc APIs you should understand these key concepts:

  • ScaleArc Server - The server running the ScaleArc appliance
  • API Key - API key is a unique identifier generated by ScaleArc after successful authentication.  A valid API key is required for all API calls.
  • Cluster - Logical load balancers and each can be configured to uniquely manage SQL traffic. 
  • Data - Information pertaining to various ScaleArc services. 

 How cURL Commands Work

cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets you to transmit and receive HTTP requests and responses from the command line or a shell script, which enables you to work with the API directly. It is available for Linux distributions, Mac OS X, and Windows. For information about cURL, see http://curl.haxx.se/.

To run the cURL request examples shown in this guide, copy each example from this guide directly to the command line or a script.

Authenticate to ScaleArc Service

Authentication Request

To authenticate, issue a POST/tokens request to the appropriate ScaleArc server.

In the request body, supply username and password credentials. Your username and password are the ones that you use to log into the ScaleArc appliance. Upon successful login you can obtain your API key.


Example 1: Log in to ScaleArc (Authentication)

  1.  Get a list of required fields

curl -k -X GET https://<IP>/api/login/help

  1.  Response


Send a username and a password that you use to log into your ScaleArc appliance.  The only supported method for "login" call is POST. 

  1.  Using the information above, send credentials as follows: 

curl -k -X POST https://<IP>/api/login -d '{"username":"admin","password":"admin"}'

  1.  Response

{"success":true,"message":"Authentication was successful","timestamp":1415040025,"data":{"apikey":"3014a9af7bf5ee7afb50e39534bd2016_1490710547_12185ed2b375d5f76978b3a403a72ed4","iDB_type":"mysql","isCloud":"0"}}

  1.  Using the information above, send credentials as follows: 

curl -k -X POST https://<IP>/api/system/show_api_key -d '{"username":"admin","password":"admin", "apikey": "3014a9af7bf5ee7afb50e39534bd2016_1490710547_12185ed2b375d5f76978b3a403a72ed4

  1.  Response

{"success":true,"message":"Authentication was successful","timestamp":1415040025,"data":{"apikey":"37fab7edbf7065e2fa34cd8841df329f396baea2"}}



Now we can use this API key for our next requests.

Example 2: Update ScaleArc's hostname

curl -X PUT http://<IP>/api/network/hostname  -d '{"apikey": "37fab7edbf7065e2fa34cd8841df329f396baea2","hostname": "machine1" }'

Reminder: If you don't know which fields to send, do a GET to /help first

curl -X GET http://<IP>/api/network/hostname/help?apikey=37fab7edbf7065e2fa34cd8841df329f396baea2

Action Types

An API uses the following HTTP action types for object manipulation:

Action Type



To get information of an object


To add a new object or attribute


To update existing attributes of objects


To delete an attribute or an object

Common Response Parameters

The following table describes the common response parameters for an API:






Returns the status of an API call. Valid values are TRUE and FALSE.



Returns a message confirming the success of the call or an error message in case of failure.



Returns time in seconds since epoch (1970-01-01 00:00:00).



·         Returns an object containing requested data for a GET action.

·         In case of an ADD/UPDATE action, an echo of the request parameters is sent in the data object.

If a /help call is made then JSON contains expected_data instead of data, as well as list of supported methods (get, post, put, delete) for this API call.


More API Details from the ScaleArc UI, a step-by-step Example

After the administrator logs in to the ScaleArc UI, the API page is accessed through the Settings Menu from the top-right of the ScaleArc UI as illustrated here. Then, follow these steps to select and display the API parameters and even execute the call from the UI. Here is a step-by-step demonstration for a typical API call:

Using the API UI


1) Navigate to the API UI  
2) Retrieve the API Key for executing all subsequent API Commands  
3) Use the same Administrator username and password that you used to access ScaleArc UI  
4) API key fetched successfully  
5) Scroll through the list of APIs available.  
6) Let's take a look at the "Read/Write Split" API  
7) This is the "GET" method for this API call  
8) We still need to select the -ID- of the cluster we want to execute this API for.  
9) This API will be executed for the "CMS_Database" cluster. Note that the cluster ID "1" has been entered in the API call.  
10) Note in the "CLUSTERS" UI page that this cluster's setting for read/write split is "on"  
11) Now that the PAI call is completed, the "EXECUTE" button is available. Pressing the button now will display the results of the API call as described.  
12) Final results for the API call indicates that the "data' value of the API request is also "on". Additional details fo the API call results are also provided in the JSON reply.  





Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request