RUN@cloud » CloudBees API

CloudBees API

Last modified by Michael Neale on 2013/01/15 22:22

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:

https://api.cloudbees.com/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 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

Java Example

see here https://github.com/cloudbees/cloudbees-api-client

Tags:
Created by Spike Washburn on 2011/07/20 03:07