Swarm API

This chapter describes the REST-like API provided by Swarm, which can be used to automate common Swarm interactions or integrate with external systems.

Authentication

Swarm's API requires an authenticated connection for all data-modifying endpoints. Authenticated connections are achieved using HTTP Basic Access Authentication.

Note

If the require_login configuration flag is set to true, all API endpoints require authentication.

For example: 

curl --uapiuser:password http://myswarm/api/v1/projects

Swarm accepts a ticket from the Perforce service, which is either host-unlocked or locked to the Swarm host. It may also be possible to use a password in place of the ticket.

To acquire a ticket, run the following command: 

$ p4 -p myp4host:1666 -u apiuser login -p

Important

For a Perforce service that has been configured for security level 3, passwords are not accepted.

For more information on security levels, see:


Perforce System Administrator's Guide: Server security levels.

Note

If you use a ticket to authenticate against the Swarm API and the ticket expires, you need to acquire a new ticket to continue using the API.

If you make a request that requires authentication and you have authenticated, the response is: 

{
  "error": "Unauthorized"
}

Requests

Swarm's API includes endpoints that provide, create, and update information within Swarm.

If you make a request against an endpoint that is not supported, the response is: 

{
  "error": "Method Not Allowed"
}

GET information

Use HTTP GET requests to ask for information from the API.

For example, to get the list of reviews: 

$ curl http://myswarm/api/v1/reviews

Certain API calls support a fields parameter that allows you to specify which fields to include in the response, enabling more compact data sets. The following endpoints support fields:

  • /api/v1/projects

  • /api/v1/reviews

  • /api/v1/reviews/{id}

Fields can be expressed as a comma-separated list, or using array-notation. For example: 

$ curl 'http://myswarm/api/v1/reviews?fields=id,description,participants'

Or: 

$ curl 'http://myswarm/api/v1/reviews?fields[]=id,fields[]=description,fields[]=participants'

POST new information

Use HTTP POST requests to create information via the API.

For example, to create a review using form-encoded values: 

$ curl --uapiuser:password -d"change=12345" http://myswarm/api/v1/reviews

The response should be similar to: 

{
  "isValid": true,
  "id": 12206
}

To create a review using JSON: 

$ curl --uapiuser:password -H "Content-type: application/json" -d'{"change": 12345}' http://myswarm/api/v1/reviews

Update

Use HTTP PATCH requests to update information via the API.

If your HTTP client does not support PATCH requests, you can emulate this behaviour by submitting an HTTP POST with a "?_method=PATCH" parameter.

Responses

Swarm's API responses are JSON formatted.