CloudBees API
The Query API is a HTTP-based programming interface that provides operations for managing the CloudBees services and resources.
An example implementation of this can be found here https://github.com/cloudbees/cloudbees-api-client
IMPORTANT note
The query api described here is not really a "RESTful" api - the best example of how it works is in the code: https://github.com/cloudbees/cloudbees-api-client. If you are consuming this api from any JVM language, it is recommended to do that. We do have plans for a full RESTful style api in future covering a wider set of features.
API Actions
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)
- parameters - JSON object for non-standard config parameters
- containerType - the type of application container (valid values: jboss or tomcat)
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:
- domain - the account/domain name
- 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:
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 CloudBees for api requests. For the 0.1 version of the API, this is your CloudBees 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 api being used (expected value: 0.1)
Query API Authentication
The CloudBees Query API supports two forms of authentication:
- OAuth authentication
- Signed URLs
OAuth authentication (for registered OAuth Client Apps only)
If you have registered an OAuth client app with CloudBees, you were assigned a Client ID and Secret. This can be used to obtain OAuth tokens that can be used to impersonate the user who is accessing your application. To use OAuth with the CloudBees API, your application must obtain a token with one or more of the following scopes:
- https://api.cloudbees.com/oauth/api_all - scope with authority to make all CloudBees API calls. [Note that this is a very powerful scope, that many users will not allow]
- ...more scopes with reduced privileges will be available soon
Once your application obtains an API-scoped OAuth token, you can sent HTTPS requests to the API using the Bearer authentication scheme. This scheme relies on the standard HTTP Authorization header,with a type of 'Bearer' and a value which is the Base64-encoded version of the user's OAuth token obtained by your application.
The following is an example of a curl command that uses the Bearer authentication scheme:
curl -H "Authorization: Bearer BASE64_ENCODED_TOKEN" https://api.cloudbees.com/api?action=application.list
Signed URLs
Signed 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 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