API - Getting Started

Purpose:  

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

Question:

How do I use the ScaleArc API?  

Answer:

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.

Examples

Example 1: Log in to ScaleArc (Authentication)

1.  Get a list of required fields
   

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

2.  Response

{"success":true,"message":"","timestamp":1415037317,"expected_data":{"username":"/^[-_.a-zA-Z0-9]{3,50}$/","password":"/^.{4,}$/"},"supported_methods":["post"]}

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

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

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

4.  Response

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

5.  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

6.  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:

Common Response Parameters

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

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: