About the API Implementation

API Version

This document describes version 1 of the API. All requests go to paths that begin with /api/1/.

API Authentication

Authentication to the Uptrack API server uses a username and an API key that are specified in custom HTTP headers. All requests must include X-Uptrack-User and X-Uptrack-Key HTTP headers that include the API username and API key of the user who is making the request.

API Request Format

API requests or responses include JSON-encoded data in the request body. Set a Content-Type header of application/json in all requests. Similarly, include an Accept: header that contains the value application/json in any requests that expect a response containing content.

These headers aren't required, as the API only uses JSON-encoded data, but future versions of the API might use other data-encoding formats.

Available API Requests

The following are descriptions of the API requests that are available.

GET /api/1/machines

The GET /api/1/machines API request returns a list of all the registered systems. This list includes inactive systems that have uninstalled Uptrack or any systems that haven't reported to the Uptrack server recently. The list doesn't include systems that you have hidden by using the web interface. The response shows a list of systems, which are represented as dictionaries, as shown in the following example:

 {
      hostname: uptrack.example.com,
      ip: 184.73.248.238,
      last_seen: '2010-04-26T18:03:43Z',
      uuid: e82ba0ae-ad0a-4b92-a776-62b502bfd29d,
      active: true,
      status: uptodate,
      authorization: allowed,
      autoinstall: true,
      mmap_min_addr: 4096,
      uptrack_client_version: 1.2.1
   }

The following fields are provided in the response:

status

Contains one of the following values:

outofdate - Updates are available for installation on the system.
unsupported - The system's kernel isn't supported by Ksplice Uptrack.
uptodate - All available updates have been installed on the system.

authorization

Contains one of the following values:

allowed - The system is allowed to communicate with the Uptrack servers and to receive updates.
denied - The system has been denied access to the Uptrack servers by using the web interface, uptrack-api-authorize, or the authorize API call.
pending - This account has the default deny policy set for new systems, and the system hasn't yet been authorized.

autoinstall

Indicates whether autoinstall is set on the system.

mmap_min_addr

Is the value of /proc/sys/vm/mmap_min_addr or None for clients before version 1.0.3.

uptrack_client_version

Is the version of the Uptrack client that the system is running.

GET /api/1/machine/$UUID/describe

The GET /api/1/machine/$UUID/describe API request returns information about the system with the specified UUID. The UUID of a system is stored in /var/lib/uptrack/uuid and can be retrieved by using the machines query. The response is a dictionary of the same form that GET /api/1/machines returns, except that it includes the following fields:

effective_kernel: Ksplice has applied all the important security and reliability updates that are needed to bring the system into line with this kernel version.
group: The group to which the system is assigned. You can also use the web interface to manage system groups.
installed_updates: A list of 2-element dictionaries of the form {'ID': update_id, 'Name': update_name} that represent the updates installed on the system. update_id is the ID code of an update (for example, diptbg4f) and update_name is a short descriptive name for the update (for example, CVE-2010-0415: Information Leak in sys_move_pages).
original_kernel: The kernel version of the system before any Ksplice updates were applied.
steps: A list of two-element lists of the form [action, {'ID': update_id, 'Name': update_name}], representing the updates that need to be installed or removed to update the system. For the action argument, you can specify Install or Remove. Note that an existing update is removed if it superseded by a more recent version.

POST /api/1/machine/$UUID/authorize

The POST /api/1/machine/$UUID/authorize API request authorizes the system with the specified UUID to access the Uptrack service if you have configured the account to deny access to new systems.

The content is a dictionary of the following form:

{authorized: boolean}

Specify the boolean argument as true to authorize the system or false to revoke authorization.

POST /api/1/machine/$UUID/group

The POST /api/1/machine/$UUID/group API request changes the group of the system with the specified UUID.

The content is a dictionary that uses the following form:

{group_name: string}

In the previous example, string is the name of the new group. The group is created if it doesn't already exist. Note that if the account doesn't have a system with the specified UUID, the request results in an HTTP 404 error.

To remove a system from a group, you can set the group to a different name, or you can specify an empty string for no group.

Interaction Sample

The following example, which is provided as a reference only, shows an interaction that might take place when using the Uptrack API.

This conversation takes place with the server uptrack.api.ksplice.com over port 443 by using the Secure Sockets Layer (SSL) protocol.

The following is a request for a list of registered systems that's made to the server:

GET /api/1/machines HTTP/1.1
Host: uptrack.api.ksplice.com
Accept: application/json
X-Uptrack-User: jo.admin@example.com
X-Uptrack-Key: 3af3c2c1ec407feb0fdc9fc1d8c4460c

The server authenticates the request and responds with a list of the systems, for example:

HTTP/1.0 200 OK
Date: Mon, 03 May 2010 21:09:48 GMT
Content-Type: application/json

[{"status": "uptodate", "uuid": "e82ba0ae-ad0a-4b92-a776-62b502bfd29d",
  "active": true, "ip": "192.168.248.238", "hostname": "utclient.example.com",
  "authorization": "allowed", "autoinstall": true,
  "last_seen": "2010-04-26T18:03:43Z", "mmap_min_addr": 4096,
  "uptrack_client_version": "1.2.1"}]