Use the Lab Management API

The Lab Management Web Services API is a set of callable methods that enable your build and test systems to integrate with Lab Management's capabilities to manage infrastructure for software development.

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 Lab Management nodes are located on. HTTPS support is required to make API requests from anywhere else. It is recommended that you use HTTPS for your API requests whenever possible.

The Lab Management API is implemented as a client distributed with Lab Management, cubit_api_client.py. This client runs on any platform that Python runs on. 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 redistribute 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

See CollabXchange for examples of successful integrations using the Lab Management REST API.

Note: Use of Lab Management's Web Services API is governed under the same terms as your use of the rest of TeamForge Lab Management. 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 the access of users who overuse the service.

Generate a new API key or view your current API key from your Lab Management Start page.
Important: Your API key allows you to execute any API calls within Lab Management as you, as if you were logged into the Web interface. Keep your key safe using the same types of precautions you would use for your password.
Set yourself up to use signed API methods. Lab Management API methods are signed to avoid embedding your API key in the URL body of requests and keep it secure from snooping.
1. Make a request to the server for a token. This will be used along with your API key to encrypt the arguments.
2. Encode the arguments into a hash using a known secret (your API key, plus your token). We call this hash the signature.
3. 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.
To use a signed method, pass the following command-line options to the cubit_api_client.py program:

-s

This indicates that the method is a signed method, and an authentication should be performed.

--api-user|-u username

This argument specifies the username to authenticate as.

--api-key|-k api_key

This argument specifies your API key. You can generate and view your API key from your Lab Management Start Page. You can change your API key at anytime independently of your Lab Management 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
```
To use an unsigned method, fetch the following URL: https://<cubit.domain>/cubit_api/1/status"/> (where <cubit.domain> is the domain name of your Lab Management site).
Tip: The status method is the most basic of all the API methods, and will always return an OK string as a response.

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>
                    
```