RESTful interfaces // Swarm 2014.1: User Guide

RESTful interfaces

Extending Swarm can be done in several ways. Modules are the primary mechanism for extending Swarm, but there are also RESTful interfaces for getting and setting state on objects in Swarm.

Creating events in the activity feed

Swarm supports adding events from any other tool via a simple RESTful-ish endpoint. Posts to /activity/add with the following options will be added to the event queue.

type: required - type of activity, e.g. 'jira'
user: required - user that performed the action
action: required - post-tense action, e.g. 'created'
target: required - label for target, e.g. 'issue 1234'
description: optional - description of object or activity
time: optional - time of activity (defaults to now)
streams: optional - list of streams to display on
link: optional - string URL of target

It is easy to post a Swarm event using curl. For example, warn your co-workers of the ever increasing threat of dingoes with:

curl --cookie-jar cjar --data 'user=ADMINUSER' --data 'password=ADMINPASS' http://myswarm/login
curl --cookie-jar cjar --data "type=coffee&user=A dingo&action=ate&target=a baby" http://myswarm/activity/add

Note

As the example demonstrates, posting events requires a login as a Perforce user with admin-level privileges. This prevents unauthorized events from being included in activity streams.

Setting the test status for a code review

There are two end points to set the test status for a review:

/reviews/54321/tests/pass
/reviews/54321/tests/fail

where >54321 should be replaced with the id of the review in question.

Web services

A number of Swarm actions provide JSON formatted output or accept simple POST parameters to do updates.

Interesting examples include, but are not limited to:

http://myswarm/activity

Input param type can filter results with one of these values: review, comment, job, change
Input param after can specify the ID of the last seen result to get additional entries after that point
Adding /streams/stream-id can filter results for a particular stream e.g. project-p4d, user-gnicol, personal-gnicol, review-12345
```
http://myswarm/projects/edit/project id
http://myswarm/projects/add
```
POSTing to these actions, with project id replaced with your project id, can allow adding or editing projects
```
http://myswarm/reviews/?format=json
http://myswarm/project/p4d/reviews
```
Input param filter can limit results.