Overview

The pulse™ remote API provides functions that allow you to:

• Login/logout
• Monitor project status
• Monitor build results
• Control project state
• Shutdown the pulse™ server

All of these functions are accessed via the base URL (assuming the web application port is the default of 8080):

http://<host>:8080/xmlrpc

Important Do not add a trailing slash ('/') to the URL above. If you get 404 errors trying to access the API, double-check the URL you specified.

All of the calls in the API are methods on the RemoteApi class. For example, using python:

#! /usr/bin/env python

from xmlrpclib import ServerProxy, Error

server = ServerProxy("http://pulse:8080/xmlrpc")

try:
    print server.RemoteApi.getVersion()
except Error, v:
    print "Error:", v

Usage Pattern

The remote API is secured using the same user accounts used to log in via the web interface. Every remote API call (excepting RemoteAPI.getVersion and RemoteAPI.login) requires you to provide an authentication token as credentials. These tokens are obtained using the call RemoteAPI.login, by providing the login name and password for a registered user. Tokens are valid for half an hour after issue, and may be explicitly invalidated using RemoteAPI.logout. Different API calls require different levels of access, as noted in the reference documentation for the call. The level of access granted depends on the user details provided to RemoteAPI.login. For example, if you log in as a user with administrative rights, you will have access to all functions.

The token-based security mechanism gives rise to the following usage pattern:

1. Login obtain an authentication token
2. Make the desired API calls, passing the saved token as credentials
3. Logout to invalidate the token

For example:

server = ServerProxy("http://pulse:8080/xmlrpc")

try:
    token = server.RemoteApi.login("admin", "secret")
    print server.RemoteApi.getProjectState(token, "my project")
    server.RemoteApi.logout(token)
except Error, v:
    print "Error:", v