API
From Stax
Contents |
Stax Query API
The Stax Query API is an HTTP-based programming interface that provides operations for managing the Stax Java and MySQL services.
API Methods
application.deployArchive
Deploys an application archive using the specified app_id. If the application ID does not exist, it will be created.
Note: this method uploads files, so it uses the HTTP multipart/form-data content type instead of application/form-url-encoded.
Parameters
- app_id* - fully qualified application id (format: username/appname)
- archive* - archive file content
- archive_type* - type of the archive. Expected values: ear or war
- description - deployment description
- environment - config environment to use when running the application
- src - optional archive source (makes the source available for download to application members)
application.delete
Deletes an application
Parameters:
- app_id* - fully qualified application id (format: username/appname)
application.info
Returns basic information about an application (id, title, create date, status, urls)
Parameters:
- app_id* - fully qualified application id (format: username/appname)
application.list
Returns a list of the applications that the authenticated requestor is a member of.
Parameters: none
application.restart
Redeploys the specified application using the currently active snapshot.
Parameters:
- app_id* - fully qualified application id (format: username/appname)
application.setMeta
Updates the application metadata fields
Parameters:
- app_id* - fully qualified application id (format: username/appname)
- title* - the application title
application.start
Starts a stopped application
Parameters:
- app_id* - fully qualified application id (format: username/appname)
application.stop
Undeploys an application from all servers, and displays a "service unavailable" message for inbound application requests.
Parameters:
- app_id* - fully qualified application id (format: username/appname)
- reason - description of why the application was stopped
database.create
Creates a new MySQL database
Parameters
- database_id* - the database name (must be unique)
- database_password* - the database password
- database_username* - the database username
database.delete
Deletes a MySQL database
Parameters:
- database_id* - the database name
database.info
Retrieves the basic info about a database (owner, username, password, create date, status, host, port)
Parameters:
- database_id* - the database name (must be unique)
- fetch_password - optionally fetch the database password. Expected values: true or false. Default is false.
database.list
Returns the list of databases available to the authenticated requestor.
Parameters: none
Using the API
Query requests are GET or POST HTTP requests that are composed of:
- a set of common parameters that must be specified in all requests (see common query parameters below)
- a parameter named action (see [api:actions])
- a set parameters supported by the specified action.
The HTTP endpoint for all requests is:
http://api.stax.net/api
Common Query parameters
All Query API requests support a common set of parameters that are used to setup various aspects of the query invocation.
- api_key (required) - ID assigned by Stax for api requests. For the 0.1 version of the API, this is your Stax username.
- format (optional, default: xml) - the format of the result. Currently, only the xml format is supported.
- sig - the authentication signature of the request. See 'Query API authentication' below to calculate this value.
- sig_version (required) - the version of the signature algorithm used to sign the request (expected value: 1)
- timestamp (required) - the time that the query was generated formatted as the number of seconds since Jan 1, 1970 UTC.
- v (required) - the version of the Stax api being used (expected value: 0.1)
Query API Authentication
All requests to the query API include a signature parameter which is used to validate that the request was generated by a sender that knows the secret associated with the API key. The method for creating the signature is as follows:
- Calculate the signature input string
- Gather the list of query parameters that will be used in the request query string or POST body (this includes the query action parameters and the default parameters required for every query API request, with the exception of the sig parameter, which is being calculated)
- Sort all query parameters by parameter name
- Create the signature string by concatenating the sorted name/value pairs
- Generate the signature value
- Create an MD5 hash of the signature input string + your Stax API secret
- Convert the resulting hash bytes to base64
- Use the resulting value as the sig request parameter
Whenever a query API request is received by the server, the server will calculate the signature for the request based upon this same method, using the secret associated with the api_key included in the request. If the signature sent by the client does not match the signature calculated by the server, then the request will be rejected
Java Example
String createSignatureValue(Map<String, String> queryParameters, String apiSecret)
{
//sort the parameters by parameter name
TreeMap<String, String> sortedParams = new TreeMap<String, String>(queryParameters);
//concatenate the parameter name-value pairs
StringBuilder sigData = new StringBuilder();
for (Map.Entry<String, String> entry : sortedParams.entrySet()) {
String key = entry.getKey();
String value = entry.getValue();
sigData.append(key);
sigData.append(value);
}
//create md5 hash of sigData+secret
String sigString = sigData.toString() + apiSecret;
StringBuilder sigValue = new StringBuilder();
MessageDigest md5 = MessageDigest.getInstance("MD5");
byte[] md5Bytes = md5.digest(sigString.getBytes("CP1252"));
for (int i = 0; i < md5Bytes.length; ++i) {
sigValue.append(String.format("%02x", md5Bytes[i] & 0xFF));
}
return sigValue.toString();
}
