Common API endpoints
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.
If the require_login
configuration flag
is set to true
, all API endpoints require 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 server allows it.
To acquire a ticket, run the following command:
$ p4 -p myp4host:1666 -u apiuser login -p
For a Helix Core server that has been configured for security level 3, passwords are not accepted. For more information on security levels, see on Server security levels in the Helix Core Server Administrator Guide: Fundamentals.
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 not 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 <literal>GET</literal> requests to ask for information from the API.
For example, to get the list of reviews:
$ curl https://myswarm.url/api/v9/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/v9/projects
-
/api/v9/reviews
-
/api/v9/reviews/{id}
Fields can be expressed as a comma-separated list, or using array-notation. For example:
$ curl 'https://myswarm.url/api/v9/reviews?fields=id,description,participants'
or:
$ curl 'https://myswarm.url/api/v9/reviews?fields[]=id,fields[]=description,fields[]=participants'
POST new information
Use HTTP <literal>POST</literal> requests to create information via the API.
For example, to create a review using form-encoded values:
$ curl -u "apiuser:password" -d"change=12345" https://myswarm.url/api/v9/reviews
The response should be similar to:
{
"isValid": true,
"id": 12206
}
To create a review using JSON:
$ curl -u "apiuser:password" -H "Content-type: application/json" \
-d'{"change": 12345}' https://myswarm.url/api/v9/reviews
Update
Use HTTP <literal>PATCH</literal> 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.
Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
Your search for returned result(s).