Getting Started with CUBiT Web Services

1. 1. CollabNet CUBiT Web Services

The CUBiT Web Services API is a set of callable methods which allows your build and test systems to integrate with CUBiT's capabilities to manage infrastructure for software development.

This API is under active development. We have started with the most common actions which would need to be performed on an automated basis, and will expand this list over time as we receive feedback about what developers want and need. Please let us know if there are missing features or bugs!

The CUBiT Web Services are a network-accessible API to the capabilities of CollabNet's CUBiT product. Using a standard HTTP/HTTPS client, users can programmatically perform actions like rebuilding and powercycling hosts, and uploading files into the Project Build Library.

API methods come in two forms: signed and unsigned. Signed methods require authentication, in accordance with the User Authentication documentation, while unsigned methods do not require authentication. Most methods within CUBiT are signed methods, since they perform actions that require authentication.

In the rest of this document, we will discuss using the client distributed with CUBiT, cubit_api_client.py. This client is distributed along with CUBiT and runs on any platform that Python runs on. In addition, pre-compiled executables, which do not require Python, are available for Windows. The client is open-source, and you are free to modify it and re-distribute it in accordance with its license terms. You can use it to build the basis of your own client in Python or any other language.

2. Unsigned Methods

Using unsigned methods in CUBiT Web Services is very easy. For example, to invoke an unsigned method, fetch the following URL:
https://cubit.domain/cubit_api/1/status (where cubit.domain is the domain name of your CUBiT site).

The status method is the most basic of all the API methods, and will always return an OK string as a repsonse.

To demonstrate the unsigned status method with cubit_api_client.py:

cubit_api_client.py -l http://cubit.domain/cubit_api/1 status
cubit_api_client.py: OK

Again, this time with XML output:

cubit_api_client.py -l http://cubit.domaincubit_api/1 --xml status
<?xml version='1.0'?>
<cubit version='1'>
    <status>OK</status>
</cubit>

3. Signed Methods

Most of the API methods in CUBiT, and all of the most useful ones, are signed methods which require authentication to use. The cubit_api_client.py client makes using these signed methods easy by handling the authentication negotiation for you.

In signed methods, you must pass the following command-line options to the cubit_api_client.py program:

1. -s: This indicates that the method is a signed method, and an authentication should be performed.
2. --api-user|-u username: This argument specifies the username to authenticate as.
3. --api-key|-k api_key: This argument specifies your API key. You can generate and view your API key from your CUBiT Start Page. You can change your API key at anytime independently of your CUBiT password.

In addition to these required arguments, most web services require other parameters. These are specified as space-separated key=value pairs. For example, consider the following command, which will allocate the host "cu012.cubit.domain" to the user "alice" in the project "webtesting", while authenticating as the user "bob" with bob's API key:

cubit_api_client.py --api-url=http://cubit.domain/cubit_api/1 --api-user=bob --api-key=713cdf90-2549-1350-80c3-2d0bcf9a1142 -s alloc_host  host=cu012.cubit.domain alloc_user=alice alloc_proj=webtesting

The above examples should help you get started with using CUBiT's web services.

4. Authentication

This paragrph describes the process of authenticating to CUBiT's web services API. The intended audience of this document is users who are developing their own clients or are interested in learning more about the authentication implementation.

Prerequisites

In order to use authentication with CUBiT's web services API, you must first obtain an API key. You can generate a new key or view your current API key from your Start Page within CUBiT. Your API key allows you to execute any API calls within CUBIT as you, so keep your key safe using the same types of precautions you would use for your password.

The API requires a client which speaks at least HTTP, if you are going to be making requests only from the secure local network that CUBiT nodes are located on. HTTPS support is required to make API requests from anywhere else, but HTTPS will work anywhere. It is recommended that you always use HTTPS for your API requests whenever it is possible.

Permissions

When using signed API methods and your API key, you will be authenticated at the same level of access as when you are logged into the CUBiT web interface.

Signing

CUBiT API methods are signed to avoid embedding your API key in the URL body of requests, to keep it secure from snooping. Using signed methods is a three-step process:

1. First, you make a request to the server for a token, which will be used along with your API key to encrypt the arguments.
2. Second, you encode the arguments into a hash using a known secret (your API key, plus your token). We call this hash the signature.
3. Finally, you make a second request to the server, passing the signature and the list of key/value argument pairs. If your key/value pairs contain unicode data, the hashed list of arguments must be UTF-8 encoded, otherwise, UTF-8 encoding of the argument hash is optional.

5. Terms of Use

Use of CUBiT's Web Services API are governed under the same terms as your use of the rest of CollabNet's CUBiT product. While we do not place any restrictions on the number of API calls any user can make in any time period, we request that users make use of only the API calls that they really need, and we reserve the right to limit user's access who are overusing the service.