Swarm API basics

This section describes the API endpoints that are commonly used when constructing an API call to Swarm.

Authentication

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

For example:

curl -u "apiuser:ticket" https://myswarm.url/api/v9/projects

Swarm accepts a ticket from the Helix Core Server (previous versions of Swarm required this ticket to be host-unlocked, this is no longer true since Swarm 2017.1). It might also be possible to use a password in place of the ticket if your Helix Core Server allows it.

To acquire a ticket, run the following command:

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

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

HTTP/1.1 200 OK

{
  "error": "Unauthorized"
}

Requests

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

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

HTTP/1.1 200 OK

{
  "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 using the v11 API:

curl -u "username:ticket" "https://my-swarm-host/api/v11/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.

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

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects/jam?fields=id,description,members"

The following endpoints support fields:

API (v9)

• /api/v9/activity

• /api/v9/comments

• /api/v9/groups

• /api/v9/groups/{id}

• /api/v9/projects

• /api/v9/reviews

• /api/v9/reviews/{id}

• /api/v9/users

• /api/v9/workflows

• /api/v9/workflows/{id}

API (v11)

• /api/v11/files/{id}

• /api/v11/projects

• /api/v11/projects/{id}

• /api/v11/reviews

• /api/v11/reviews/{id}

• /api/v11/reviews/{id}/files

• /api/v11/reviews/{id}/testruns

• /api/v11/search

• /api/v11/specs/{spec}/fields

• /api/v11/testdefinitions

• /api/v11/workflows

• /api/v11/workflows/{id}

POST new information

Use HTTP POST requests to create information via the API.

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

curl -u "apiuser:ticket" -X POST -d"change=12345" https://myswarm.url/api/v9/reviews

The response should be similar to:

HTTP/1.1 200 OK

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

To create a review using JSON:

curl -u "apiuser:ticket" -H "Content-type: application/json" -X POST -d'{"change": 12345}' https://myswarm.url/api/v9/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 behavior by submitting an HTTP POST with a "?_method=PATCH" parameter.

Pagination

Most Swarm endpoints that provide data include the ability to paginate their results.

Each time data is requested, up to max results are included in the response, as is a value called lastSeen. lastSeen identifies the id of the last entry included in the results. If there are no further results, lastSeen is null.

To get the next set of results, include after set to the value of lastSeen in the API request. Entries up to and including the id specified by after are excluded from the response, and the next max entries are included.

See the Activity endpoint for example usage that demonstrates pagination.

Responses

Swarm’s API responses are JSON formatted.