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.

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

For example:

$ curl -u "apiuser:password" https://myswarm.url/api/v8/projects

Swarm accepts a ticket from the Helix Versioning Engine (previous versions of Swarm required this ticket to be host-unlocked, this is no longer true since Swarm 2017.1). 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

For a Helix Versioning Engine that has been configured for security level 3, passwords are not accepted.

For more information on security levels, see:
Helix Versioning Engine 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/v8/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:

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

$ curl 'https://myswarm.url/api/v8/reviews?fields=id,description,participants'

Or:

$ curl 'https://myswarm.url/api/v8/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/v8/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/v8/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.

API versions

The current Swarm API version is v8. Here is a list of historical API versions:

API version Swarm Release Date Description

v8

2017.4

December 2017

Include support for default reviewers on a project or project branch.

v7

2017.3

October 2017

Include support for groups as participants of a review and groups as moderators of a project branch.

v6

2017.1

May 2017

Include support for activity dashboard, archiving of inactive reviews, cleaning completed reviews and for voting reviews up and down.

v5

2016.3

December 2016

Include support for limiting comments to a specific review version.

v4

2016.2

October 2016

Include support for private projects, as well as file-level and line-level inline comments.

v3

2016.1 SP1

September 2016

Include new endpoint for comments.

v2

2016.1

May 2016

Include new endpoints for projects, groups, etc.

v1.2

2015.3

October 2015

Add author filter to the list reviews endpoint.

v1.1

2014.4

January 2015

Addition of required reviewers, and apiVersions.

v1

2014.3

July 2014

Initial release.

API Endpoints

This section includes coverage for each of the major endpoints provided by the API.

Activity : Swarm Activity List

GET /api/v8/activity

Summary: List Activity Entries

Description

Retrieve the Activity List.

Parameters
Parameter Description Type Parameter Type Required Default Value

change

Optionally filter activity entries by associated Changelist ID. This only includes records for which there is an activity entry in Swarm.

integer

form

No

stream

Optional activity stream to query for entries. This can include user-initiated actions (user-alice), activity relating to a user’s followed projects/users (personal-alice), review streams (review-1234), and project streams (project-exampleproject).

string

form

No

type

Type of activity, e.g., change, comment, job, or review.

string

form

No

after

An activity ID to seek to. Activity entries up to and including the specified ID are excluded from the results and do not count towards max. Useful for pagination. Commonly set to the lastSeen property from a previous query.

integer

query

No

max

Maximum number of activity entries to return. This does not guarantee that max entries are returned. It does guarantee that the number of entries returned won’t exceed max. Server-side filtering may exclude some activity entries for permissions reasons.

integer

query

No

100

fields

An optional comma-separated list (or array) of fields to show. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Successful Response:
HTTP/1.1 200 OK

{
  "activity": [
    {
      "id": 123,
      "action": "committed",
      "behalfOf": null,
      "behalfOfExists": false,
      "change": 1,
      "date": "2016-01-15T12:12:12-08:00",
      "depotFile": null,
      "description": "test\n",
      "details": [],
      "followers": [],
      "link": ["change", {"change": 1}],
      "preposition": "into",
      "projectList": {"restricted": ["main"]},
      "projects": {"restricted": ["main"]},
      "streams": ["review-2", "user-foo", "personal-foo", "project-restricted"],
      "target": "change 1",
      "time": 1404776681,
      "topic": "changes/1",
      "type": "change",
      "url": "/changes/1",
      "user": "bruno",
      "userExists": true
    }
  ],
  "lastSeen": 1
}
Examples of usage
Fetching review history

To get the latest activity entries on a review:

curl -u "username:password" "https://myswarm.url/api/v8/activity?stream=review-1234\
&fields=id,date,description,type\
&max=2"

You can tweak max and fields to fetch the data that works best for you.

Swarm responds with an array of activity entities, and a lastSeen value that can be used for pagination:

{
  "activity": [
    {
      "id": 10,
      "date": "2016-04-15T16:10:32-07:00",
      "description": "This is a test comment.",
      "type": "comment"
    },
    {
      "id": 9,
      "date": "2016-03-31T13:48:15-07:00",
      "description": "Updating RELNOTE review",
      "type": "review"
    }
  ],
  "lastSeen": 9
}
Activity pagination

To get the second page of activity entries for a review (based on the previous example):

curl -u "username:password" "https://myswarm.url/api/v8/activity?stream=review-1234\
&fields=id,date,description,type\
&max=2\
&lastSeen=9"

Swarm again responds with a list of activity entities and a lastSeen value:

{
  "activity": [
    {
      "id": 8,
      "date": "2016-03-30T12:12:12-07:00",
      "description": "This is the first test comment.",
      "type": "comment"
    },
    {
      "id": 7,
      "date": "2016-03-29T12:13:14-07:00",
      "description": "Updating RELNOTE review",
      "type": "review"
    }
  ],
  "lastSeen": 7
}

POST /api/v8/activity

Summary: Create Activity Entry

Description

Creates an entry in the Activity List. Note: admin-level privileges are required for this action.

Parameters
Parameter Description Type Parameter Type Required

type

Type of activity, used for filtering activity streams (values can include change, comment, job, review).

string

form

Yes

user

User who performed the action.

string

form

Yes

action

Action that was performed - past-tense, e.g., created or commented on.

string

form

Yes

target

Target that the action was performed on, e.g., issue 1234.

string

form

Yes

topic

Optional topic for the activity entry. Topics are essentially comment thread IDs. Examples: reviews/1234 or jobs/job001234.

string

form

No

description

Optional description of object or activity to provide context.

string

form

No

change

Optional changelist ID this activity is related to. Used to filter activity related to restricted changes.

integer

form

No

streams[]

Optional array of streams to display on. This can include user-initiated actions (user-alice), activity relating to a user’s followed projects/users (personal-alice), review streams (review-1234), and project streams (project-exampleproject).

array (of strings)

form

No

link

Optional URL for target.

string

form

No

Successful Response:
HTTP/1.1 200 OK

{
  "activity": {
    "id": 123,
    "action": "ate",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "details": [],
    "description": "",
    "followers": [],
    "link": "",
    "preposition": "for",
    "projects": [],
    "streams": [],
    "target": "the manual",
    "time": 1404776681,
    "topic": "",
    "type": "comment",
    "user": "A dingo"
  }
}
Examples of usage
Creating an activity entry

To create a plain activity entry:

curl -u "username:password" -d "type=job" -d "user=jira" -d "action=punted" -d "target=review 123" \
     "https://myswarm.url/api/v8/activity"

JSON Response:

{
  "activity": {
    "id": 1375,
    "action": "punted",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "description": "",
    "details": [],
    "followers": [],
    "link": "",
    "preposition": "for",
    "projects": [],
    "streams": [],
    "target": "review 123",
    "time": 1461607739,
    "topic": "",
    "type": "job",
    "user": "jira"
  }
}
Linking an activity entry to a review

Linking activity entries to reviews is useful. This involves providing link, stream, and topic fields in the activity data. The link field is used to make the review 123 string in the activity entry clickable. The stream field is needed so that the activity entry can be attached to the review in the Swarm interface. The topic field is used to link the activity entry to the comment thread for that topic, in the event that a user wants to comment on the activity.

To create a fully linked activity entry:

curl -u "username:password" -d "type=job" -d "user=jira" -d "action=punted" -d "target=review 123" \
     -d "streams[]=review-123" \
     -d "link=reviews/123" \
     -d "topic=reviews/123" \
     "https://myswarm.url/api/v8/activity"

Swarm responds with an activity entity:

{
  "activity": {
    "id": 1375,
    "action": "punted",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "description": "",
    "details": [],
    "followers": [],
    "link": "reviews/123",
    "preposition": "for",
    "projects": [],
    "streams": ["review-123"],
    "target": "review 123",
    "time": 1461607739,
    "topic": "reviews/123",
    "type": "job",
    "user": "jira"
  }
}

Changes : API controller providing a service for changes

GET /api/v8/changes/{change}/affectsprojects

Summary: Get projects, and branches, affected by a given change id.

Description

All authenticated users are able to use this API.

Successful Response:
HTTP/1.1 200 OK

{
    "change": {
        "id":"1050",
        "projects": {
            "jam": [
                "live",
                "main"
            ]
        }
    }
}

GET /api/v8/changes/{change}/defaultreviewers

Summary: Get default reviewers for a given change id.

Description

All authenticated users are able to use this API.

Successful Response:
HTTP/1.1 200 OK

{
"change": {
    "id": "1050",
    "defaultReviewers": {
        "groups": {
            "group1": {"required": "1"},
            "group2": {}
        },
        "users": {
            "user1": {},
            "user2": {"required": "true"}
        }
    }
}
}

Comments : Swarm Comments

GET /api/v8/comments/

Summary: Get List of Comments

Description

List comments.

Parameters
Parameter Description Type Parameter Type Required Default Value

after

A comment ID to seek to. Comments up to and including the specified ID are excluded from the results and do not count towards max. Useful for pagination. Commonly set to the lastSeen property from a previous query.

integer

query

No

max

Maximum number of comments to return. This does not guarantee that max comments are returned. It does guarantee that the number of comments returned won’t exceed max.

integer

query

No

100

topic

Only comments for given topic are returned. Examples: reviews/1234, changes/1234 or jobs/job001234.

string

query

No

context[version]

If a reviews/1234 topic is provided, limit returned comments to a specific version of the provided review.

integer

query

No

ignoreArchived

Prevents archived comments from being returned. (v5+)

boolean

query

No

tasksOnly

Returns only comments that have been flagged as tasks. (v5+)

boolean

query

No

taskStates

Limit the returned comments to ones that match the provided task state (one or more of open, closed, verified, or comment). (v5+)

array (of strings)

query

No

fields

An optional comma-separated list (or array) of fields to show for each comment. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Examples of successful responses
Successful Response:
HTTP/1.1 200 OK

{
  "topic": "",
  "comments": {
    "51": {
      "id": 51,
      "attachments": [],
      "body": "Short loin ground round sin reprehensible, venison west participle triple.",
      "context": [],
      "edited": null,
      "flags": [],
      "likes": [],
      "taskState": "comment",
      "time": 1461164347,
      "topic": "reviews/885",
      "updated": 1461164347,
      "user": "bruno"
    }
  },
  "lastSeen": 51
}
lastSeen can often be used as an offset for pagination, by using the value in the after parameter of subsequent requests.
When no results are found, the comments array is empty:
HTTP/1.1 200 OK

{
  "topic": "jobs/job000011",
  "comments": [],
  "lastSeen": null
}
Examples of usage
Listing comments

To list comments:

curl -u "username:password" "https://my-swarm-host/api/v8/comments\
?topic=reviews/911&max=2&fields=id,body,time,user"

Swarm responds with a list of the first two comments for review 911 and a lastSeen value for pagination:

{
  "topic": "reviews/911",
  "comments": {
    "35": {
      "id": 35,
      "body": "Excitation thunder cats intelligent man braid organic bitters.",
      "time": 1461164347,
      "user": "bruno"
    },
    "39": {
      "id": 39,
      "body": "Chamber tote bag butcher, shirk truffle mode shabby chic single-origin coffee.",
      "time": 1461164347,
      "user": "swarm_user"
    }
  },
  "lastSeen": 39
}
Paginating a comment listing

To obtain the next page of a comments list (based on the previous example):

curl -u "username:password" "https://my-swarm-host/api/v8/comments\
?topic=reviews/911&max=2&fields=id,body,time,user&after=39"

Swarm responds with the second page of results, if any comments are present after the last seen comment:

{
  "topic": "reviews/911",
  "comments": {
    "260": {
      "id": 260,
      "body": "Reprehensible do lore flank ham hock.",
      "time": 1461164349,
      "user": "bruno"
    },
    "324": {
      "id": 324,
      "body": "Sinter lo-fi temporary, nihilist tote bag mustache swag consequence interest flexible.",
      "time": 1461164349,
      "user": "bruno"
    }
  },
  "lastSeen": 324
}

POST /api/v8/comments/

Summary: Add A Comment

Description

Add a comment to a topic (such as a review or a job)

Parameters
Parameter Description Type Parameter Type Required Default Value

topic

Topic to comment on. Examples: reviews/1234, changes/1234 or jobs/job001234.

string

form

Yes

body

Content of the comment.

string

form

Yes

taskState

Optional task state of the comment. Valid values when adding a comment are comment and open. This creates a plain comment or opens a task, respectively.

string

form

No

comment

flags[]

Optional flags on the comment. Typically set to closed to archive a comment.

array (of strings)

form

No

context[file]

File to comment on. Valid only for changes and reviews topics. Example: //depot/main/README.txt.

string

form

No

context[leftLine]

Left-side diff line to attach the inline comment to. Valid only for changes and reviews topics. If this is specified, context[file] must also be specified.

integer

form

No

context[rightLine]

Right-side diff line to attach the inline comment to. Valid only for changes and reviews topics. If this is specified, context[file] must also be specified.

integer

form

No

context[content]

Optionally provide content of the specified line and its four preceding lines. This is used to specify a short excerpt of context in case the lines being commented on change during the review. When not provided, Swarm makes an effort to build the content on its own - as this involves file operations, it could become slow.

array (of strings)

form

No

context[version]

With a reviews topic, this field specifies which version to attach the comment to.

integer

form

No

Successful Response contains Comment entity:
HTTP/1.1 200 OK

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "Best. Comment. EVER!",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "bruno"
  }
}
Examples of usage
Create a comment on a review

To create a comment on a review:

curl -u "username:password" \
     -d "topic=reviews/2" \
     -d "body=This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end." \
     "https://my-swarm-host/api/v8/comments"

JSON Response:

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end.",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}
Open a task on a review

To create a comment on a review, and flag it as an open task:

curl -u "username:password" \
     -d "topic=reviews/2" \
     -d "taskState=open" \
     -d "body=If you could go ahead and attach a cover page to your TPS report, that would be great." \
     "https://my-swarm-host/api/v8/comments"

JSON Response:

{
  "comment": {
    "id": 43,
    "attachments": [],
    "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "open",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

PATCH /api/v8/comments/{id}

Summary: Edit A Comment

Description

Edit a comment

Parameters
Parameter Description Type Parameter Type Required

id

ID of the comment to be edited

integer

path

Yes

topic

Topic to comment on. Examples: reviews/1234, changes/1234 or jobs/job001234.

string

form

No

body

Content of the comment.

string

form

Yes

taskState

Optional task state of the comment. Note that certain transitions (such as moving from open to verified) are not possible without an intermediate step (addressed, in this case). Examples: comment (not a task), open, addressed, verified.

string

form

No

flags[]

Optional flags on the comment. Typically set to closed to archive a comment.

array (of strings)

form

No

Successful Response contains Comment entity:
HTTP/1.1 200 OK

{
  "comment": {
    "id": 1,
    "attachments": [],
    "body": "Best. Comment. EVER!",
    "context": [],
    "edited": 123466790,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/42",
    "updated": 123456790,
    "user": "bruno"
  }
}
Examples of usage
Edit and archive a comment on a review

To edit and archive a comment on a review:

curl -u "username:password" \
     -X PATCH \
     -d "flags[]=closed" \
     -d "body=This comment wasn't as excellent as I may have lead you to believe. A thousand apologies." \
     "https://my-swarm-host/api/v8/comments/42"

JSON Response:

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "This comment wasn't as excellent as I may have lead you to believe. A thousand apologies.",
    "context": [],
    "edited": 123466790,
    "flags": ["closed"],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}
Flag a task as addressed on a review

To flag an open task as addressed on a review:

curl -u "username:password" \
     -X PATCH \
     -d "taskState=addressed" \
     "https://my-swarm-host/api/v8/comments/43"

JSON Response:

{
  "comment": {
    "id": 43,
    "attachments": [],
    "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
    "context": [],
    "edited": 123466790,
    "flags": ["closed"],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Groups : Swarm Groups

GET /api/v8/groups/

Summary: Get List of Groups

Description

Returns the complete list of groups in Swarm.

Parameters
Parameter Description Type Parameter Type Required Default Value

after

A group ID to seek to. Groups prior to and including the specified ID are excluded from the results and do not count towards max. Useful for pagination. Commonly set to the lastSeen property from a previous query.

string

query

No

max

Maximum number of groups to return. This does not guarantee that max groups are returned. It does guarantee that the number of groups returned won’t exceed max.

integer

query

No

100

fields

An optional comma-separated list (or array) of fields to show for each group. Omitting this parameter or passing an empty value shows all fields.

string

query

No

keywords

Keywords to limit groups on. Only groups where the group ID, group name (if set), or description contain the specified keywords are returned.

string

query

No

Successful Response:
HTTP/1.1 200 OK

{
  "groups": [
    {
      "Group": "test-group",
      "MaxLockTime": null,
      "MaxResults": null,
      "MaxScanRows": null,
      "Owners": [],
      "PasswordTimeout": null,
      "Subgroups": [],
      "Timeout": 43200,
      "Users": ["bruno"],
      "config": {
        "description": "Our testing group",
        "emailAddress": "test-group3@host.domain",
        "emailFlags": [],
        "name": "Test Group",
        "useMailingList": true
      }
    }
  ]
}
Examples of usage
Listing groups

To list groups:

curl -u "username:password" \
     "https://myswarm.url/api/v8/groups?keywords=test-group&fields=Group,Owners,Users,config&max=2"

Swarm responds with a list of groups:

{
  "groups": [
    {
      "Group": "test-group",
      "Owners": [],
      "Users": ["bruno"],
      "config": {
        "description": "Our testing group",
        "emailAddress": "test-group@host.domain",
        "emailFlags": {
          "reviews": "1",
          "commits": "0"
        },
        "name": "Test Group",
        "useMailingList: true
      }
    },
    {
      "Group": "test-group2",
      "Owners": [],
      "Users": ["bruno"],
      "config": {
        "description": "Our second testing group",
        "emailAddress": "test-group2@host.domain",
        "emailFlags": [],
        "name": "Test Group 2",
        "useMailingList: true
      }
    }
  ],
  "lastSeen": "test-group2"
}
Paginating the groups list

Based on the previous example, we can pass a lastSeen value of test-group2 to see if there are any subsequent groups in Swarm.

curl -u "username:password" \
     "https://myswarm.url/api/v8/groups?keywords=test-group&fields=Group,config&max=2&lastSeen=test-group2"

Swarm responds with a list of groups (minus the Owners and Users fields, as we haven’t requested them):

{
  "groups": [
    {
      "Group": "test-group3",
      "config": {
        "description": "Our 3rd testing group",
        "emailAddress": "test-group3@host.domain",
        "emailFlags": [],
        "name": "Test Group 3",
        "useMailingList": true
      }
    }
  ],
  "lastSeen": "test-group3"
}

GET /api/v8/groups/{id}

Summary: Get Group Information

Description

Retrieve information about a group.

Parameters
Parameter Description Type Parameter Type Required

id

Group ID

string

path

Yes

fields

An optional comma-separated list (or array) of fields to show for each group. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Successful Response:
HTTP/1.1 200 OK

{
  "group": {
    "Group": "test-group",
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": [],
    "PasswordTimeout": null,
    "Subgroups": [],
    "Timeout": 43200,
    "Users": ["bruno"],
    "config": {
      "description": "Our testing group",
      "emailFlags": [],
      "name": "Test Group"
    }
  }
}
Examples of usage
Fetching a group

To fetch an individual group:

curl -u "username:password" "https://myswarm.url/api/v8/groups/my-group"

Swarm responds with the group entity:

{
  "group": {
    "Group": "test-group",
    "LdapConfig": null,
    "LdapSearchQuery": null,
    "LdapUserAttribute": null,
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": [],
    "Users": ["bruno"],
    "config": {
      "description": "Our testing group",
      "emailAddress": "test-group@host.domain",
      "emailFlags": {
        "reviews": "1",
        "commits": "0"
      },
      "name": "Test Group",
      "useMailingList": true
    }
  }
}
Limiting returned fields

To limit the returned fields when fetching an individual group:

curl -u "username:password" "https://myswarm.url/api/v8/groups/my-group?fields=Group,Owners,Users,config"

Swarm responds with the group entity:

{
  "group": {
    "Group": "test-group",
    "Owners": [],
    "Users": ["bruno"],
    "config": {
      "description": "Our testing group",
      "emailFlags": [],
      "name": "Test Group"
    }
  }
}

POST /api/v8/groups/

Summary: Create a new Group

Description

Creates a new group in Swarm.

Parameters
Parameter Description Type Parameter Type Required

Group

Group identifier string.

string

form

Yes

Users

An optional array of group users. At least one of Users, Owners, or Subgroups is required.

array

form

No

Owners

An optional array of group owners. At least one of Users, Owners, or Subgroups is required.

array

form

No

Subgroups

An optional array of subgroups. At least one of Users, Owners, or Subgroups is required.

array

form

No

config[name]

An optional full name for the group.

string

form

No

config[description]

An optional group description.

string

form

No

config[emailAddress]

The email address for this group.

string

form

No

config[emailFlags][reviews]

Email members when a new review is requested.

boolean

form

No

config[emailFlags][reviews]

Email members when a new review is requested.

boolean

form

No

config[useMailingList]

Whether to use the configured email address or expand individual members addresses.

boolean

form

No

Successful Response:
HTTP/1.1 200 OK

{
  "group": {
    "Group": "test-group",
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": [],
    "PasswordTimeout": null,
    "Subgroups": [],
    "Timeout": null,
    "Users": ["alice"],
    "config": {
      "description": "Test test test",
      "emailAddress": "test-group@host.domain",
      "emailFlags": [],
      "name": "TestGroup",
      "useMailingList": true
    }
  }
}
Creating a group
  • Only users with super privileges in the Helix Versioning Engine (p4d), or users with admin privileges in p4d versions 2012.1 or newer, can create groups.

  • This API version is only capable of setting specific fields: Group, Users, Owners, Subgroups, config. Any other fields specified in the creation request are ignored.

To create a new group:

curl -u "username:password" \
     -d "Group=my-group" \
     -d "Owners[]=alice" \
     -d "Owners[]=bob" \
     -d "Users[]=bruno" \
     -d "Users[]=user2" \
     -d "config[description]=This group is special to me." \
     -d "config[name]=My Group" \
     -d "config[emailFlags][reviews]=1" \
     -d "config[emailFlags][commits]=0" \
     -d "config[emailAddress]=my-group@host.domain" \
     -d "config[useMailingList]=false" \
     "https://myswarm.url/api/v8/groups"

Assuming that the authenticated user has permission, Swarm responds with the new group entity:

{
  "group": {
    "Group": "my-group",
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": ["username"],
    "PasswordTimeout": null,
    "Subgroups": [],
    "Timeout": null,
    "Users": [],
    "config": {
      "description": "This group is special to me.",
      "emailFlags": {
        "reviews": "1",
        "commits": "0"
      },
      "name": "My Group",
      "useMailingList": true
    }
  }
}

PATCH /api/v8/groups/{id}

Summary: Edit a Group

Description

Change the settings of a group in Swarm. Only super users and group owners can perform this action.

Parameters
Parameter Description Type Parameter Type Required

id

Group ID

string

path

Yes

Users

An optional array of group users.

array

form

No

Owners

An optional array of group owners.

array

form

No

Subgroups

An optional array of group subgroups.

array

form

No

config[name]

An optional full name for the group.

string

form

No

config[description]

An optional group description.

string

form

No

config[emailAddress]

The email address for this group.

string

form

No

config[emailFlags][commits]

Email members when a change is committed.

boolean

form

No

config[emailFlags][reviews]

Email members when a new review is requested.

boolean

form

No

config[useMailingList]

Whether to use the configured email address or expand individual members addresses.

boolean

form

No

Successful Response:
HTTP/1.1 200 OK

{
  "group": {
    "Group": "test-group",
    "Users": [],
    "Owners": [],
    "Subgroups": [],
    "config": {
      "description": "New Group Description",
      "name": "TestGroup",
      "useMailingList": true
    }
  }
}
Editing a group
  • Only users with super privileges in the Helix Versioning Engine, or group owners, can edit groups.

  • This API version is only capable of modifying specific fields: Users, Owners, Subgroups, config. Any other fields specified in the edit request are ignored.

Here is how to update the name, description, and emailFlags configuration of the group my-group:

curl -u "username:password" -X PATCH \
     -d "config[description]=This group is special to me." \
     -d "config[name]=My Group" \
     -d "config[emailFlags][commits]=1" \
     "https://myswarm.url/api/v8/groups/my-group"

Assuming that the authenticated user has permission, Swarm responds with the modified group entity:

{
  "group": {
    "Group": "my-group",
    "Users": [],
    "Owners": [],
    "Subgroups": [],
    "config": {
      "description": "This group is special to me.",
      "emailAddress": "test-group@host.domain",
      "emailFlags": {
        "reviews": "1",
        "commits": "1"
      },
      "name": "My Group",
      "useMailingList": true
    }
  }
}

DELETE /api/v8/groups/{id}

Summary: Delete a Group

Description

Delete a group. Only super users and group owners can perform this action.

Parameters
Parameter Description Type Parameter Type Required

id

Group ID.

string

path

Yes

Successful Response:
HTTP/1.1 200 OK

{
  "id": "test-group"
}
Deleting a group
Only super users and group owners can delete groups.
curl -u "username:password" -X DELETE "https://myswarm.url/api/v8/groups/my-group"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted group:

{
  "id": "my-group"
}

Index : Basic API controller providing a simple version action

GET /api/v8/version

Summary: Show Version Information

Description

This can be used to determine the currently-installed Swarm version, and also to check that Swarm’s API is responding as expected.

Successful Response:
HTTP/1.1 200 OK

{
    "year": "2017",
    "version": "SWARM/2017.3-MAIN/8499605 (2017/10/25)"
}
Note: year refers to the year of the Swarm release, not necessarily the current year.

Projects : Swarm Projects

GET /api/v8/projects/

Summary: Get List of Projects

Description

Returns a list of projects in Swarm that are visible to the current user. Administrators will see all projects, including private ones.

Parameters
Parameter Description Type Parameter Type Required

fields

An optional comma-separated list (or array) of fields to show for each project. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Successful Response:
HTTP/1.1 200 OK

{
  "projects": [
    {
      "id": "testproject3",
      "branches": [
        {
          "id": "main",
          "name": "main",
          "paths": ["//depot/main/TestProject/..."],
          "moderators": [],
          "moderators-groups": []
        }
      ],
      "deleted": false,
      "description": "Test test test",
      "followers": [],
      "jobview": "subsystem=testproject",
      "members": ["alice"],
      "name": "TestProject",
      "owners": [],
      "private": false,
      "subgroups": []
    }
  ]
}
Listing projects

To list all projects:

curl -u "username:password" "https://my-swarm-host/api/v8/projects?fields=id,description,members,name"

Pagination is not currently supported by this endpoint. Swarm responds with a list of all projects:

{
  "projects": [
    {
      "id": "testproject1",
      "description": "Test test test",
      "members": ["alice"],
      "name": "TestProject"
    },
    {
      "id": "testproject2",
      "description": "Test test test",
      "members": ["alice"],
      "name": "TestProject"
    }
  ]
}

Project administrators wishing to see the tests and deploy fields must fetch projects individually.

GET /api/v8/projects/{id}

Summary: Get Project Information

Description

Retrieve information about a project.

Parameters
Parameter Description Type Parameter Type Required

id

Project ID

string

path

Yes

fields

An optional comma-separated list (or array) of fields to show for each project. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Successful Response:
HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject4",
    "defaults": [],
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": []
      }
    ],
    "deleted": false,
    "description": "Test test test",
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "subgroups": []
  }
}
Fetching a project

To fetch an individual project:

curl -u "username:password" \
     "https://my-swarm-host/api/v8/projects/testproject2?fields=id,description,members,name"

Swarm responds with a project entity:

{
  "project": {
    "id": "testproject2",
    "defaults": [],
    "description": "Test test test",
    "members": ["alice"],
    "name": "TestProject 2"
  }
}

Project administrators have access to additional fields (tests and deploy) when fetching individual projects using this endpoint.

POST /api/v8/projects/

Summary: Create a new Project

Description

Creates a new project in Swarm.

Parameters
Parameter Description Type Parameter Type Required

name

Project Name (is also used to generate the Project ID)

string

form

Yes

members

An array of project members.

array

form

Yes

subgroups

An optional array of project subgroups.

array

form

No

owners

An optional array of project owners.

array

form

No

description

An optional project description.

string

form

No

private

Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false)

boolean

form

No

deploy

Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"}

array

form

No

tests

Configuration for testing/continuous integration.

array

form

No

branches

Optional branch definitions for this project.

array

form

No

jobview

An optional jobview for associating certain jobs with this project.

string

form

No

emailFlags[change_email_project_users]

Email members, moderators and followers when a change is committed.

boolean

form

No

emailFlags[review_email_project_members]

Email members and moderators when a new review is requested.

boolean

form

No

defaults

An optional array of defaults at a project level (for example default reviewers).

array

form

No

Examples of successful responses
Successful Response:
HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject5",
    "defaults": [],
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "Test test test",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Successful Response:
HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject6",
    "defaults": {"user2":{"required":true}},
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": {
             "reviewers":{
                 "groups":{"swarm-group-group1":{"required":"1"}},
                 "users":{"user1":{"required":true}}
             }
        }
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Examples of usage
Creating a new project

To create a project:

curl -u "username:password" \
     -d "name=TestProject 3" \
     -d "description=The third iteration of our test project." \
     -d "members[]=alice" \
     -d "members[]=bob" \
     "https://my-swarm-host/api/v8/projects/"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject3",
    "defaults": [],
    "branches": [],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "The third iteration of our test project.",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice", "bob"],
    "name": "TestProject 3",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Creating a private project with branches

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch - an example of this accompanies the PATCH endpoint documentation.

Projects are public by default. Marking a project as Private requires using {private: true} in JSON, and using -d "private=1" in regular form-encoded requests.

Form-encoded requests only accept 0 for false in boolean values — using the word false will be evaluated as a non-zero (and therefore non-false) value.
curl -u "username:password" \
     -d "name=TestProject 4" \
     -d "private=1" \
     -d "members[]=bob" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     "https://my-swarm-host/api/v8/projects"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject-4",
    "defaults": [],
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": true,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Creating a project to add default reviewers (
curl -u "<user>:<password>" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '"name": "testproject-4", \
         "members": ["bob"], \
         "defaults":{"reviewers":{"user2":{"required":true}} \
         "branches":[{ \
           "name":"Branch One", \
           "paths":{"//depot/main/TestProject/..."} \
           "defaults":{"reviewers":{"swarm-group-group1":{"required":"1"},"user1":{"required":true}}]' \
     "https://my-swarm-host/api/v8/projects/testproject-4"

Or without JSON content:

curl -u "username:password" \
     -X PATCH \
     -d "name=TestProject 4" \
     -d "members[]=bob" \
     -d "defaults[reviewers][user2][required]=true" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[0][defaults][reviewers][swarm-group-group1][required]=1" \
     -d "branches[0][defaults][reviewers][user1][required]=true" \
     "https://my-swarm-host/api/v8/projects/testproject-4"

Swarm responds with project entity similar to:

{
  "project": {
    "id": "testproject-4",
    "defaults": ["user2":["required":true]]],
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": ["reviewers":["swarm-group-group1":["required":"1"], "user1":["required":true]]]
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

PATCH /api/v8/projects/{id}

Summary: Edit a Project

Description

Change the settings of a project in Swarm. If a project has owners set, only the owners can perform this action.

Parameters
Parameter Description Type Parameter Type Required

id

Project ID

string

path

Yes

name

Project Name (changing the project name does not change the project ID)

string

form

No

members

An array of project members.

array

form

No

subgroups

An optional array of project subgroups.

array

form

No

owners

An optional array of project owners.

array

form

No

description

Your project description.

string

form

No

private

Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false)

boolean

form

No

deploy

Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"}

array

form

No

tests

Configuration for testing/continuous integration.

array

form

No

branches

Optional branch definitions for this project.

array

form

No

jobview

A jobview for associating certain jobs with this project.

string

form

No

emailFlags[change_email_project_users]

Email members, moderators and followers when a change is committed.

boolean

form

No

emailFlags[review_email_project_members]

Email members and moderators when a new review is requested.

boolean

form

No

defaults

An optional array of defaults at a project level (for example default reviewers).

array

form

No

Examples of successful responses
Successful Response:
HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject7",
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Successful Response:
HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject8",
    "defaults": {"user2":{"required":true}},
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": [],
        "moderators-groups": [],
        "defaults": {
             "reviewers":{
                 "groups":{"swarm-group-group1":{"required":"1"}},
                 "users":{"user1":{"required":true}}
             }
         }
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Examples of usage
Editing a project

To edit a project:

It is safe to edit a project without specifying branches, but the instructions for adding branches contain important information for modifying branch configuration.
curl -u "username:password" \
     -X PATCH
     -d "description=Witness the power of a fully operational Swarm project." \
     "https://my-swarm-host/api/v8/projects/testproject3"

Swarm responds with the updated project entity:

{
  "project": {
    "id": "testproject3",
    "branches": [],
    "defaults": [],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "Witness the power of a fully operational Swarm project.",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject 3",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Editing a project to add a moderated branch and make the project public

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch.

If you have existing branches, you must specify all of them in the query to avoid data loss. This operation sets the value of the entire branches property to match the provided input.

Marking a private project as Public requires using {private: false} in JSON, or using -d "private=0" in regular form-encoded requests.

Form-encoded requests only accept 0 for false in boolean values — using the word false will be evaluated as a non-zero (and therefore non-false) value.
curl -u "username:password" \
     -X PATCH \
     -d "private=0" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[1][name]=Branch Two" \
     -d "branches[1][paths][]=//depot/main/SecondBranch/..." \
     -d "branches[1][moderators][]=bob" \
     -d "branches[1][moderators-groups][]=group1" \
     "https://my-swarm-host/api/v8/projects/testproject-4"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject-4",
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": []
      },
      {
        "paths": [
          "//depot/main/SecondBranch/..."
        ],
        "name": "Branch Two",
        "id": "branch-two",
        "moderators": ["bob"],
        "moderators-groups": ["group1"],
        "defaults": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}
Editing a project to add default reviewers
curl -u "<user>:<password>" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '"defaults":{"reviewers":{"user2":{"required":true}} \
         "branches":[{ \
           "name":"Branch One", \
           "paths":{"//depot/main/TestProject/..."} \
           "defaults": { \
               "reviewers":{ \
                   "groups":{"group1":{"required":"1"}}, \
                   "users":{"user1":{"required":true}} \
               } \
           }]' \
     "https://my-swarm-host/api/v8/projects/testproject-4"

Or without JSON content:

curl -u "username:password" \
     -X PATCH \
     -d "name=TestProject 4" \
     -d "members[]=bob" \
     -d "defaults[reviewers][user2][required]=true" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[0][defaults][reviewers][groups][group1][required]=1" \
     -d "branches[0][defaults][reviewers][users][user1][required]=true" \
     "https://my-swarm-host/api/v8/projects/testproject-4"

Swarm responds with project entity similar to:

{
  "project": {
    "id": "testproject-4",
    "defaults": ["user2":["required":true]]],
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": [],
        "moderators-groups": [],
        "defaults": {
               "reviewers":{
                   "groups":{"group1":{"required":"1"}},
                   "users":{"user1":{"required":true}}
               }
           }
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

DELETE /api/v8/projects/{id}

Summary: Delete a Project

Description

Mark a Swarm project as deleted. The project ID and name cannot be reused. If a project has owners set, only the owners can perform this action.

Parameters
Parameter Description Type Parameter Type Required

id

Project ID

string

path

Yes

Successful Response:
HTTP/1.1 200 OK

{
  "id": "testproject"
}
Deleting a project

Super users, administrators, and owners can delete projects. Members can delete projects that have no owners set.

curl -u "username:password" -X DELETE "https://my-swarm-host/api/v8/projects/testproject3"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted project:

{
  "id": "testproject3"
}

Reviews : Swarm Reviews

GET /api/v8/dashboards/action

Summary: Get reviews for action dashboard

Description

Gets reviews for the action dashboard for the authenticated user

Successful Commit contains Review and Commit Entities:
HTTP/1.1 200 OK

{
  "lastSeen": 120,
  "reviews": [
    {
      "id": 7,
      "author": "swarm_admin",
      "changes": [6],
      "comments": [0,0],
      "commits": [6],
      "commitStatus": [],
      "created": 1485793976,
      "deployDetails": [],
      "deployStatus": null,
      "description": "test\n",
      "groups": ["swarm-project-test"],
      "participants": {"swarm_admin":[]},
      "pending": false,
      "projects": {"test":["test"]},
      "roles": ["moderator|reviewer|required_reviewer|author"],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1485958875,
      "updateDate": "2017-02-01T06:21:15-08:00"
    }
  ],
  "totalCount": null
}
Getting reviews for the action dashboard

To list reviews:

curl -u "username:password" "http://my-swarm-host/api/v8/dashboards/action"

Swarm responds with a list of the latest reviews, a totalCount field, and a lastSeen value for pagination:

{
  "lastSeen": 120,
  "reviews": [
    {
      "id": 7,
      "author": "swarm_admin",
      "changes": [6],
      "comments": [0,0],
      "commits": [6],
      "commitStatus": [],
      "created": 1485793976,
      "deployDetails": [],
      "deployStatus": null,
      "description": "test\n",
      "groups": ["swarm-project-test"],
      "participants": {"swarm_admin":[]},
      "pending": false,
      "projects": {"test":["test"]},
      "roles": ["moderator|reviewer|required_reviewer|author"],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1485958875,
      "updateDate": "2017-02-01T06:21:15-08:00"
    }
  ],
  "totalCount": null
}

GET /api/v8/reviews/

Summary: Get List of Reviews

Description

List and optionally filter reviews.

Parameters
Parameter Description Type Parameter Type Required Default Value

after

A review ID to seek to. Reviews up to and including the specified id are excluded from the results and do not count towards max. Useful for pagination. Commonly set to the lastSeen property from a previous query.

integer

query

No

max

Maximum number of reviews to return. This does not guarantee that max reviews are returned. It does guarantee that the number of reviews returned won’t exceed max. Server-side filtering may exclude some reviews for permissions reasons.

integer

query

No

1000

fields

An optional comma-separated list (or array) of fields to show. Omitting this parameter or passing an empty value shows all fields.

string

query

No

author[]

One or more authors to limit reviews by. Reviews with any of the specified authors are returned. (v1.2+)

array (of strings)

query

No

change[]

One or more change IDs to limit reviews by. Reviews associated with any of the specified changes are returned.

array (of integers)

query

No

hasReviewers

Boolean option to limit to reviews to those with or without reviewers. Use true or false for JSON-encoded data, 1 for true and or 0 for false for form-encoded data. The presence of the parameter without a value is evaluated as true.

boolean

query

No

ids[]

One or more review IDs to fetch. Only the specified reviews are returned. This filter cannot be combined with the max parameter.

array (of integers)

query

No

keywords

Keywords to limit reviews by. Only reviews where the description, participants list or project list contain the specified keywords are returned.

string

query

No

participants[]

One or more participants to limit reviews by. Reviews with any of the specified participants are returned.

array (of strings)

query

No

project[]

One or more projects to limit reviews by. Reviews affecting any of the specified projects are returned.

array (of strings)

query

No

state[]

One or more states to limit reviews by. Reviews in any of the specified states are returned.

array (of strings)

query

No

passesTests

Boolean option to limit reviews by tests passing or failing. Use true or false for JSON-encoded data, 1 for true and 0 for false for form-encoded data. The presence of the parameter without a value is evaluated as true.

string

query

No

notUpdatedSince

Option to fetch unchanged reviews. Requires the date to be in the format YYYY-mm-dd, for example 2017-01-01. Reviews to be returned are determined by looking at the last updated date of the review.

string

query

No

hasVoted

Should have the value 'up' or 'down' to filter reviews that have been voted up or down by the current authenticated user.

string

query

No

myComments

True or false to support filtering reviews that include comments by the current authenticated user.

boolean

query

No

Examples of successful responses
Successful Response:
HTTP/1.1 200 OK

{
  "lastSeen": 12209,
  "reviews": [
    {
      "id": 12206,
      "author": "swarm",
      "changes": [12205],
      "comments": 0,
      "commits": [],
      "commitStatus": [],
      "created": 1402507043,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Review Description\n",
      "participants": {
        "swarm": []
      },
      "pending": true,
      "projects": [],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1402518492
    }
  ],
  "totalCount": 1
}
Swarm returns null for totalCount if no search filters were provided. lastSeen can often be used as an offset for pagination, by using the value in the after parameter of subsequent requests.
When no results are found, the reviews array is empty:
HTTP/1.1 200 OK

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}
Examples of usage
Listing reviews

To list reviews:

curl -u "username:password" "https://my-swarm-host/api/v8/reviews?max=2&fields=id,description,author,state"

Swarm responds with a list of the latest reviews, a totalCount field, and a lastSeen value for pagination:

{
  "lastSeen": 120,
  "reviews": [
    {
      "id": 123,
      "author": "bruno",
      "description": "Adding .jar that should have been included in r110\n",
      "state": "needsReview"
    },
    {
      "id": 120,
      "author": "bruno",
      "description": "Fixing a typo.\n",
      "state": "needsReview"
    }
  ],
  "totalCount": null
}

The totalCount field is populated when keywords are supplied. It indicates how many total matches there are. If keywords are not supplied the totalCount field remains null, indicating that the list of all reviews is being queried.

Paginating a review listing

To obtain the next page of a reviews list (based on the previous example):

curl -u "username:password" "https://my-swarm-host/api/v8/reviews\
?max=2&fields=id,description,author,state&after=120"

Swarm responds with the second page of results, if any reviews are present after the last seen review:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "description": "Updating Java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": null
}
Finding reviews for a change or a list of changes

Given a list of change IDs (5, 6, 7), here is how to check if any of them have reviews attached:

curl -u "username:password" "https://my-swarm-host/api/v8/reviews\
?max=2&fields=id,changes,description,author,state&change\[\]=5&change\[\]=6&change\[\]=7"

Swarm responds with a list of reviews that include these changes:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "changes": [5],
      "description": "Updating Java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "changes": [6,7],
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": 2
}

If no corresponding reviews are found, Swarm responds with an empty reviews list:

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}
Finding inactive reviews (by checking the last updated date)
curl -u "username:password" "https://my-swarm-host/api/v8/reviews\
?max=2&fields=id,changes,description,author,state&notUpdatedSince=2017-01-01"

Swarm responds with a list of reviews that have not been updated since the notUpdatedSince date:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "changes": [5],
      "description": "Updating Java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "changes": [6,7],
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": 2
}
Finding reviews I have voted up
curl -u "username:password" "https://my-swarm-host/api/v8/reviews\
?max=2&fields=id,changes,description,author,state&hasVoted=up"

Swarm responds with a list of reviews that include these changes:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "changes": [5],
      "description": "Updating Java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "changes": [6,7],
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": 2
}

If no corresponding reviews are found, Swarm responds with an empty reviews list:

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}
Finding reviews I have commented on (current authenticated user)
curl -u "username:password" "https://my-swarm-host/api/v8/reviews\
?max=2&fields=id,changes,description,author,state&myComments=true"

Swarm responds with a list of reviews that include these changes:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "changes": [5],
      "description": "Updating Java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "changes": [6,7],
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": 2
}

If no corresponding reviews are found, Swarm responds with an empty reviews list:

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}

GET /api/v8/reviews/{id}

Summary: Get Review Information

Description

Retrieve information about a review.

Parameters
Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

fields

An optional comma-separated list (or array) of fields to show. Omitting this parameter or passing an empty value shows all fields.

string

query

No

Successful Response:
HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "author": "bruno",
    "changes": [10667],
    "commits": [10667],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "alex_qc": [],
      "bruno": {
        "vote": 1,
        "required": true
      },
      "vera": []
    },
    "reviewerGroups": {
      "group1" : [],
      "group2" : {
        "required" : true
      },
      "group3" : {
        "required" : true,
        "quorum": "1"
      }
    },
    "pending": false,
    "projects": {
      "swarm": ["main"]
    },
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": {
      "url": "http://jenkins.example.com/job/project_ci/123/"
    },
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}
Example 404 Response:
HTTP/1.1 404 Not Found

{
  "error": "Not Found"
}
Fetching a review

To fetch a review:

curl -u "username:password" "https://my-swarm-host/api/v8/reviews/123"

Swarm responds with a review entity:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122,124],
    "commits": [124],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "alex_qc": [],
      "bruno": {
        "vote": 1,
        "required": true
      },
      "vera": []
    },
    "reviewerGroups": {
      "group1" : [],
      "group2" : {
        "required" : true
      },
      "group3" : {
        "required" : true,
        "quorum": "1"
      }
    },
    "pending": false,
    "projects": {
      "swarm": ["main"]
    },
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": {
      "url": "http://jenkins.example.com/job/project_ci/123/"
    },
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": []
  }
}

POST /api/v8/reviews/

Summary: Create a Review

Description

Pass in a changelist ID to create a review. Optionally, you can also provide a description and a list of reviewers.

Parameters
Parameter Description Type Parameter Type Required

change

Change ID to create a review from

integer

form

Yes

description

Description for the new review (defaults to change description)

string

form

No

reviewers

A list of reviewers for the new review

array (of strings)

form

No

requiredReviewers

A list of required reviewers for the new review (v1.1+)

array (of strings)

form

No

reviewerGroups

A list of required reviewers for the new review (v7+)

array

form

No

Successful Response contains Review Entity:
HTTP/1.1 200 OK

{
  "review": {
    "id": 12205,
    "author": "bruno",
    "changes": [10667],
    "commits": [10667],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "reviewerGroups": {
      "group1" : [],
      "group2" : {
        "required" : true
      },
      "group3" : {
        "required" : true,
        "quorum": "1"
      }
    },
    "pending": false,
    "projects": [],
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}
Starting a review

To start a review for a committed change or a non-empty shelved changelist specifying reviewer groups:

curl -u "username:password" \
     -d "change=122" \
     -d "reviewerGroups[0][name]=group1" \
     -d "reviewerGroups[1][name]=group2" \
     -d "reviewerGroups[1][required]=true" \
     -d "reviewerGroups[2][name]=group3" \
     -d "reviewerGroups[2][required]=true" \
     -d "reviewerGroups[2][quorum]=1" \
     "https://my-swarm-host/api/v8/reviews/"

Swarm responds with the new review entity:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122],
    "commits": [],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "bruno": []
    },
    "reviewerGroups": {
      "group1" : [],
      "group2" : {
        "required" : true
      },
      "group3" : {
        "required" : true,
        "quorum": "1"
      }
    },
    "pending": true,
    "projects": [],
    "state": "needsReview",
    "stateLabel": "Needs Review",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": []
  }
}

POST /api/v8/reviews/archive/

Summary: Archiving the inactive reviews (v6+)

Description

Archiving reviews not updated since the date (v6+)

Parameters
Parameter Description Type Parameter Type Required

notUpdatedSince

Updated since date. Requires the date to be in the format YYYY-mm-dd, for example 2017-01-01

string

form

Yes

description

A description that is posted as a comment for archiving.

string

form

Yes

Successful Response:
HTTP/1.1 200 OK

{
  "archivedReviews": [
    {
      "id": 836,
      "author": "swarm",
      "changes": [789],
      "commits": [],
      "commitStatus": [],
      "created": 1461164339,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Review description\n",
      "groups": [],
      "participants": {
        "swarm": []
      },
      "pending": false,
      "projects": [],
      "state": "archived",
      "stateLabel": "Archived",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1478191607
    }
  ],
  "failedReviews": []
}
Archiving reviews inactive since 2016/06/30

To archive reviews not updated since 2016/06/30 inclusive:

curl -u "username:password" -d "notUpdatedSince=2016-06-30" \
     "https://my-swarm-host/api/v8/reviews/archive/"

Swarm responds with the list of archived reviews and failed reviews if there are any:

{
  "archivedReviews":[
    {
      "id": 911,
      "author": "swarm",
      "changes": [601],
      "commits": [],
      "commitStatus": [],
      "created": 1461164344,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Touch up references on html pages.\n",
      "groups": [],
      "participants": {
        "swarm":[]
      },
      "pending": false,
      "projects": [],
      "state": "archived",
      "stateLabel": "Archived",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1478191605
    },
    {
      "id": 908,
      "author": "earl",
      "changes": [605],
      "commits": [],
      "commitStatus": [],
      "created": 1461947794,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Remove (attempted) installation of now deleted man pages.\n",
      "groups": [],
      "participants": {
        "swarm": []
      },
      "pending": false,
      "projects": [],
      "state": "archived",
      "stateLabel": "Archived",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1478191605
    }
  ],
  "failedReviews":[
    {
    }
  ]
}

If no reviews are archived, Swarm responds with an empty reviews list:

{
  "archivedReviews": [],
  "failedReviews": []
}

POST /api/v8/reviews/{id}/changes/

Summary: Add Change to Review

Description

Links the given change to the review and schedules an update.

Parameters
Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

change

Change ID

integer

form

Yes

Successful Response contains Review Entity:
HTTP/1.1 200 OK

{
  "review": {
    "id": 12206,
    "author": "bruno",
    "changes": [10667, 12000],
    "commits": [10667, 12000],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}
Adding a change to a review

You may want to update a review from a shelved or committed change that is different from the initiating change. This is done by adding a change to the review.

To add a change:

curl -u "username:password" -d "change=124" "https://my-swarm-host/api/v8/reviews/123/changes/"

Swarm responds with the updated review entity:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122, 124],
    "commits": [],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "bruno": []
    },
    "pending": true,
    "projects": [],
    "state": "needsReview",
    "stateLabel": "Needs Review",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": [
      {
        "difference": 1,
        "stream": null,
        "change": 124,
        "user": "bruno",
        "time": 1399330003,
        "pending": true,
        "archiveChange": 124
      }
    ]
  }
}

POST /api/v8/reviews/{id}/cleanup

Summary: Clean up a review (v6+)

Description

Clean up a review for the given id.

Parameters
Parameter Description Type Parameter Type Required

reopen

Expected to be a boolean (defaulting to false). If true then an attempt will be made to reopen files into a default changelist

boolean

form

No

Successful Response:
HTTP/1.1 200 OK

{
  "complete": [
    {
      "1": ["2"]
    }
  ],
  "incomplete": []
}
Cleaning up a review with id 1.

Cleanup review number 1, reopening any files into the default changelist.

curl -u "username:password" -d "reopen=true" \
     "https://my-swarm-host/api/v8/reviews/1/cleanup"

Swarm responds with the review and the changelists cleaned. Depending on the completion they will be either detailed in 'complete' or 'incomplete'. Incomplete changelists will have messages indicating why it was not possible to complete:

  {
    "complete": [
      {
        "1": ["2"]
      }
    ],
    "incomplete": []
  }

PATCH /api/v8/reviews/{id}/state/

Summary: Transition the Review State (v2+)

Description

Transition the review to a new state. When transitioning to approved, you can optionally commit the review. (v2+)

Parameters
Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

state

Review State. Valid options: needsReview, needsRevision, approved, archived, rejected

string

form

Yes

description

An optional description that is posted as a comment for non-commit transitions. Commits that do not include a description default to using the Review description in the resulting change description.

string

form

No

commit

Set this flag to true and provide a state of approved in order to trigger the Approve and Commit action in Swarm.

boolean

form

No

wait

Instruct Swarm to wait for a commit to finish before returning.

boolean

form

No

jobs[]

When performing an 'Approve and Commit', one or more jobs can be attached to the review as part of the commit process.

stringArray

form

No

fixStatus

Provide a fix status for the attached job(s) when performing an 'Approve and Commit'. Possible status values vary by job specification, but often include: open, suspended, closed, review, fixed.

string

form

No

Examples of successful responses
Successful Response contains Review Entity:
HTTP/1.1 200 OK

{
  "review": {
    "id": 12207,
    "author": "bruno",
    "changes": [10667, 12000],
    "commits": [],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "needsRevision",
    "stateLabel": "Needs Revision",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  },
  "transitions": {
    "needsReview": "Needs Review",
    "approved": "Approve",
    "rejected": "Reject",
    "archived": "Archive"
  }
}
Successful Commit contains Review and Commit Entities:
HTTP/1.1 200 OK

{
  "review": {
    "id": 12208,
    "author": "bruno",
    "changes": [10667, 12000, 12006],
    "commits": [12006],
    "commitStatus": {
      "start": 1399326910,
      "change": 12006,
      "status": "Committed",
      "committer": "bruno",
      "end": 1399326911
    },
    "created": 1399325900,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "needsRevision",
    "stateLabel": "Needs Revision",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325905
  },
  "transitions": {
    "needsReview": "Needs Review",
    "needsRevision": "Needs Revision",
    "rejected": "Reject",
    "archived": "Archive"
  },
  "commit": 12006
}
Committing a review

To commit a review:

curl -u "username:password" -X PATCH -d "state=approved" -d "commit=1" \
     "https://my-swarm-host/api/v8/reviews/123/state/"

Swarm responds with the updated review entity, as well as a list of possible transitions for the review:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122, 124],
    "commits": [124],
    "commitStatus": {
        "start": 1399326910,
        "change": 124,
        "status": "Committed",
        "committer": "bruno",
        "end": 1399326911
      },
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "approved",
    "stateLabel": "Approved",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": []
  },
    "transitions": {
      "needsReview": "Needs Review",
      "approved": "Approve",
      "rejected": "Reject",
      "archived": "Archive"
    }
}

PATCH /api/v8/reviews/{review_id}

Summary: Update Review Description

Description

Update the description field of a review.

Parameters
Parameter Description Type Parameter Type Required

review_id

Review ID

integer

path

Yes

author

The new author for the specified review. (At least one of Author or Description are required.)

string

form

No

description

The new description for the specified review. (At least one of Description or Author are required.)

string

form

No

_method

Method Override. If your client cannot submit HTTP PATCH, use an HTTP POST with the parameter ?_method=PATCH to override.

string

query

No

Examples of successful responses
Successful Response:
HTTP/1.1 200 OK

{
  "review": {
      "id": 12306,
      "author": "swarm",
      "changes": [12205],
      "comments": 0,
      "commits": [],
      "commitStatus": [],
      "created": 1402507043,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Updated Review Description\n",
      "participants": {
        "swarm": []
      },
      "pending": true,
      "projects": [],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1402518492
  },
  "transitions": {
      "needsRevision": "Needs Revision",
      "approved": "Approve",
      "rejected": "Reject",
      "archived": "Archive"
  },
  "canEditAuthor": true
}
Swarm returns null for totalCount if no search filters were provided. lastSeen can often be used as an offset for pagination, by using the value in the after parameter of subsequent requests.
When no results are found, the reviews array is empty:
HTTP/1.1 200 OK

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}

Users : Basic API controller providing a simple version action

GET /api/v8/users/{user}/unfollowall

Summary: Unfollow all Users and Projects

Description

Admin and super users are permitted to execute unfollow all against any target user. Other users are only permitted to execute the call if they themselves are the target user

Successful Response:
HTTP/1.1 200 OK

{
    "isValid": true,
    "messages": "User {user} is no longer following any Projects or Users."
}

Extended API example

This section includes an extended API example, involving multiple API calls to answer a more complicated kind of question than any single API endpoint can provide: which reviews does a specific userid need to attend to?

The code

<?php
/**
 * vim:set ai si et ts=4 sw=4 syntax=php:
 *
 * reviews.php
 *
 * Queries the Swarm API and reports which reviews a specified user
 * needs to attend to.
 *
 * Required attention is determined by the following criteria:
 * - the user is a participant in a review
 * - and the user has not voted on the review
 * - and the user has not commented on the review
 * - or the user's comment on the review is a
 *   task that has been addressed and needs verification
 */

if (ini_set('track_errors', 1) === false) {
    echo "Warning: unable to track errors.\n";
}

# process command-line arguments
$options = getopt(
    'hs:r:v',
    array('help', 'swarm:', 'reviewer', 'verbose')
);

$swarm = '';
if (isset($options['s'])) {
    $swarm = $options['s'];
}
if (isset($options['swarm'])) {
    $swarm = $options['swarm'];
}
if (!$swarm) {
    usage('Swarm API URL not provided.');
}

$reviewer = '';
if (isset($options['r'])) {
    $reviewer = $options['r'];
}
if (isset($options['reviewer'])) {
    $reviewer = $options['reviewer'];
}
if (!$reviewer) {
    usage('Swarm reviewer not provided.');
}

$verbose = false;
if (isset($options['v']) || isset($options['verbose'])) {
    $verbose = true;
}

if (isset($options['h']) || isset($options['help'])) {
    usage();
}

function usage($message = null)
{
    if ($message) {
        echo "$message\n\n";
    }

    $script = basename(__FILE__);
    echo <<<EOU
$script: -s <Swarm URL> -u <API userid> -p <API user's password> \
  -r <reviewer userid to report on> -h

-s|--swarm     Swarm's URL (e.g. https://user@password:myswarm.url/)
-r|--reviewer  The reviewer to report on.
-h|--help      This help text.
-v|--verbose   Verbose output.

This script queries the Swarm API and reports on reviews that the
specified user needs to attend to.

Note: If your Helix Versioning Engine (p4d) has security level 3 set, you
cannot use a password to authenticate; you must acquire a host-unlocked
ticket from p4d, and use the ticket in place of a password when
communicating with the Swarm API connected to p4d.

EOU;
    exit;
}

function msg($message)
{
    global $verbose;

    if ($verbose) {
        echo $message;
    }
}

function call_api($url, $params)
{
    global $php_errormsg;

    $query    = http_build_query($params);
    $request  = $url . '?' . $query;
    $response = @file_get_contents($request);
    if ($php_errormsg) {
        echo "Unable to call api: $php_errormsg\n";
        exit;
    }

    $json = @json_decode($response, true);
    if ($php_errormsg) {
        echo "Unable to decode api response: $php_errormsg\n";
        exit;
    }

    return $json;
}

# remove trailing / from URL, if it exists
$swarm = rtrim(trim($swarm), '/');

# fetch the list of reviews
$reviews = call_api(
    "$swarm/api/v4/reviews",
    array(
        'hasReviewers' => 1, # only reviews with participants
        'participants' => array($reviewer), # only review for this reviewer
        'max'          => 9, # get plenty of reviews, if available
        'fields'       => array('id', 'description', 'commits'), # get these fields
    )
);

$report = array();
foreach ($reviews['reviews'] as $review) {
    if (is_null($review)) {
        continue;
    }

    $flag = false;
    msg('Review: ' . $review['id'] . ' ');

    # if the review is already committed, it likely does not need attention
    if (array_key_exists('commits', $review)
        && count($review['commits'])
    ) {
        msg("is committed, skipping...\n");
        continue;
    }

    # if the review has a vote from the reviewer, they are already aware
    if (array_key_exists('participants', $review)
        && array_key_exists('vote', $review['participants'][$reviewer])
    ) {
        msg("has vote from reviewer, skipping...\n");
        continue;
    }

    # if there are no open comments on the review, the reviewer's
    # attention is required
    if (array_key_exists('comments', $review)
        && $review['comments'][0] == 0
    ) {
        msg("has no open comments, skipping...\n");
        continue;
    }

    # fetch the comments for this review
    $comments = call_api(
        "$swarm/api/v4/comments",
        array(
            'topic' => 'reviews/' . $review['id'], # comments for this review
            'max'   => 9, # get plenty of comments, if available
        )
    );

    foreach ($comments['comments'] as $comment) {
        msg("\n  Comment: " . $comment['id'] . ' ');

        // skip over comments from other reviewers
        if (array_key_exists('user', $comment) && $reviewer != $comment['user']) {
            msg("is by another user, carry on...\n");
            continue;
        }

        # skip archived comments
        if (array_key_exists('flags', $comment)
            && count($comment['flags']) > 0
            && $comment['flags'][0] == 'closed'
        ) {
            msg("is archived, carry on...\n");
            continue;
        }

        # skip marked tasks
        if (array_key_exists('taskState', $comment)
            && ($comment['taskState'] == 'comment'
                || $comment['taskState'] == 'verified'
                || $comment['taskState'] == 'open'
            )
        ) {
            msg("reviewer's comment needs attention, carry on...\n");
            continue;
        }

        // anything else means that the reviewer's comment needs attention
        // by the reviewer
        $flag = true;
        msg("needs attention!\n");
        break;
    }

    // evaluation is complete. Does this review need attention?
    if ($flag) {
        $report[] = $review;
    }
}

if (count($report)) {
    echo "User '$reviewer' needs to attend to these reviews:\n";
    foreach ($report as $review) {
        $description = trim($review['description']);
        if (strlen($description) > 60) {
            $description = substr($description, 0, 60) . ' ...';
        }
        echo $review['id'] . ": $description\n";
    }
} else {
    echo "User '$reviewer' has no reviews to attend to.\n";
}

Executing the example

The example is written in PHP. To use it, download the code, or copy and paste it into a file called reviews.php. Then, execute it like this:

$ php reviews.php -s https://myswarm.host:port/ -r bob

Replace http://myswarm.host/ with the URL to your Swarm installation. Replace bob with the userid you’d like to report on.

To authenticate, insert username:password@ before the hostname. If your Helix Versioning Engine’s security counter is set to 3 or higher, you need to acquire a ticket and use the ticket in place of the password (see Authentication for details). If your Swarm is installed on a custom port, or is installed in a sub-folder, include those elements in the URL as well. For example:

$ php reviews.php -s https://me:F0FC33068BA244B1BBD8196CC9166F34@my.host:8080/swarm/ -r bob

If you do not specify the URL correctly, you might see an error like:

Unable to call api: file_get_contents(http://...@my.host:8080/swarm/api/v8/reviews?hasReviewers=1&participants%5B0%5D=bob&max=9&fields%5B0%5D=id&fields%5B1%5D=description&fields%5B2%5D=commits): failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found

If there are no errors, and the specified userid does have reviews to attend to, the output might look like:

1234: Added grapple-grommit support to woozlewobble class. @bob sh ...

1234 is the id of a review that bob should attend to, followed by the first 60 characters of the review’s description.

Pending Review Cleanup

This section contains an example script that cleans up pending changelists which are no longer needed. See the review cleanup options for how this can be done automatically when a review is committed.

For pending changelists which were present before this option was available, or for reviews which have been contributed to by multiple authors and so require super user access to tidy up, there is an API which allows the super user to bulk remove such changelists.

The script demonstrates how this API could be used. It isn’t meant as a complete solution, just a guide to demonstrate what is possible.

The code

<?php
/**
 * Perforce Swarm
 *
 * @copyright   2017 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
 */
/**
 * This example script can be used to clean up (delete) Perforce Server pending changelists automatically when run
 * as a super user. It is able to query for reviews based on parameters to establish which changelists are eligible
 * for clean up. In this way, it can be tailored to run against reviews of a user's choice.

 * Requirements for this script:
 *   - MUST be a super user
 *   - MUST populate the parameters below
 *   - MUST be using Swarm 2017.1 or later
 *
 * Usage of script
 *   php superUserReviewCleanUp.php max=10 notUpdatedSince=2017-04-01 state=approved
 *   php superUserReviewCleanUp.php max=10 author=bruno state=approved
 *
 * Each of the parameters that you can use are documented at the following URL:
 * https://www.perforce.com/perforce/doc.current/manuals/swarm/api.endpoints.html#api.endpoints.Reviews.getReviews
 *
 *
 * This returns a JSON object that contains four main objects.
 *
 * {
 *   "error": "",
 *   "help": "",
 *   "results": "[]",
 *   "search_criteria": {
 *     "fields": "id",
 *     "max": "10",
 *     "notUpdatedSince": "2017-04-01"
 *   }
 * }
 *
 * Referencing the example above:
 *
 * The error section will contain any errors that have been encountered trying to execute the script.
 *
 * The help section will populated if you have run the command php superUserReviewCleanUp.php help
 *
 * The search_criteria section indicates which parameters have been used to fetch the reviews list.
 *
 * The results section returns a JSON object of each of the reviews it has processed, which may
 * include actions that were incomplete.
 *
 * Below is an example of results being processed:
 * "814": {
 *    "complete": [],
 *    "incomplete": {
 *       "814": {
 *           "813": [
 *               "0": "Command failed: No shelved files in changelist to delete.",
 *           ]
 *       }
 *    }
 * },
 * "818": {
 *    "complete": [],
 *    "incomplete": []
 * }
 * "820": {
 *    "complete": [],
 *    "incomplete": {
 *       "820": {
 *           "821": [
 *              "0": "Command failed: No shelved files in changelist to delete.",
 *              "1": "Command failed: Usage: fix [ -d ] [ -s status ] -c changelist# jobName ...\nMissing/wrong
 *                    number of arguments."
 *           ]
 *       }
 *    }
 * },
 *
 * Some reviews may have no actions or incomplete actions. Incomplete actions indicate that additional work is required
 * and the review could not be entirely cleaned up. In the example above, the first message indicates a changelist was
 * not found. This could be because the end user has already deleted it.
 *
 * An error with the fix command can indicate that the pending changelist doesn't have any jobs linked or that the jobs
 * have already been removed.
 *
 * NOTES:
 * To make the the output print nicely, you can use the python command like this:
 *
 * php superUserReviewCleanUp.php max=10 notUpdatedSince=2018-04-01 state=approved | python -m json.tool
 *
 */


/* **************************************************** */
/* These values MUST be set before running the script.  */
/* **************************************************** */

// URL to access swarm. Must not include trailing slash.
$swarmURL = 'http://my.swarm.com';
// Username of super user
$username = '';
// Ticket for user, can be created by running "p4 -u $username login -pa"
$ticket = '';

/* **************************************************** */


// If the super user wants to reopen the files of the end user.
$reopen = true;
// Prebuild the the return message helper array.
$help = array( "help" => "", "error" => "", "results" => "", "search_criteria" => "");
// @codingStandardsIgnoreEnd
/**
 * function that make the GET or POST requests
 *
 * @param $url         Url in which we want to make our request to
 * @param bool $fetch  Set to true for a GET request, otherwise will do a POST.
 * @param array $args  These are the parameter that we pass the the GET or POST request to filter the reviews
 * @return JSON        We return a JSON object back to be worked on.
 */
function request($url, $fetch = false, $args = array())
{
    // Fetch the settings to allow this function to access them.
    global $username, $ticket, $reopen, $help;
    $curl = '';

    // If GET request fetch should be true and args shouldn't be empty
    if ($fetch === true) {
        // If is args is empty just give the url, otherwise build a http query with args elements
        $curl = empty($args) ? curl_init($url) : curl_init($url."?".http_build_query($args));
    } else {
        // Assume fetch is false and build a POST request.
        $curl = curl_init($url."/".$args['id'].'/cleanup');
        curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array('reopened'=>$reopen)));
        curl_setopt($curl, CURLOPT_POST, count($reopen));
    }
    curl_setopt($curl, CURLOPT_USERPWD, "$username:$ticket");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

    $result = curl_exec($curl);

    // Catch the error code in case Ticket expired or url doesn't return.
    $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    if ($statusCode != 200) {
        $help['error'] = array("HTTP code" => $statusCode);
    }

    curl_close($curl);
    return json_decode($result, true);
}

/**
 * Fetch a list of Reviews based on parameters
 *
 * @param $elements  Each of the args passed from command line are treated as elements
* @return JSON      We return a JSON object back to be worked on.
 */
function fetchReviews($elements)
{
    global $swarmURL, $help;
    $parameters = array();

    if ($elements !== null) {
        // Loop though each of the args we want to fetch reviews based on
        foreach ($elements as $key => $value) {
            // Break each of the element into key and value to allow use to build a array to pass to url
            $brokenDown = explode("=", $value);
            if ($key !== 0 && sizeof($brokenDown) === 2) {
                $parameters[$brokenDown[0]] = $brokenDown[1];
            }
        }
        // We only require the field id to limit the amount of data.
        $parameters['fields'] = 'id';
        // Helpful for debugging which parameters we have passed in the queue.
        $help['search_criteria'] = $parameters;
    }
    // Now make the request to the Swarm server with your field options.
    $result = request(
        "$swarmURL/api/v6/reviews",
        true,
        $parameters
    );

    // Return the JSON object back to be worked on.
    return $result;
}

/**
 * Loop though each of the Reviews passed in and run clean up for them.
 *
 * @param $reviews  JSON object of all the reviews we want to run cleanup on
 * $reviews => array(
 *      'reviews' => array(
 *          0 => array (
 *                  'id' => 134,
 *          ),
 *          1 => array (
 *                  'id' => 136,
 *          ),
 *          2 => array (
 *                  'id' => 143,
 *          ),
 *          3 => array (
 *                  'id' => 158,
 *          )
 *      )
 * )
 *
 * @return $array   return the array of work that has been carried out.
 */
function runCleanUp($reviews)
{
    global $swarmURL;
    $results = array();
    // Check if there is an reviews element of the array
    if (isset($reviews['reviews'])) {
        foreach ($reviews['reviews'] as $review) {
            // Now make the request to the Swarm for each review.
            $results[$review['id']] = request(
                "$swarmURL/api/v6/reviews",
                false,
                $review
            );
        }
    }
    return $results;
}

/**
 * The help function in case a user doesn't set the basic settings.
 *
 * @param $help    Pass the help array from main script to append the helpful message.
 * @return $array  Return the array that will be presented to the users.
 */
function helpMessage($help)
{
    $help["help"]      = array( "1" => "", "2" => "", "3" => "" );
    $help["help"]["1"] = "Please ensure you have set the Username, Ticket and Swarm URL before using this script";
    $help["help"]["2"] = "Running the script can be done by using any of the standard Swarm API fields for reviews";
    $help["help"]["3"] = "Visit https://www.perforce.com/perforce/doc.current/manuals/swarm/index.html";
    return $help;
}

// check the first argument is not help.
$helpSet = isset($argv[1]) && $argv[1] == "help" ? "help" : null;

// Check if the user has given help as a command to this script.
if (isset($argv[1]) && $helpSet == "help") {
    // Set the $help array with the help message.
    $help = helpMessage($help);
}

// Check if the basic user ticket and swarmurl are set.
if (!empty($username) && !empty($ticket) && !empty($swarmURL) && $helpSet != "help") {
    try {
        $help["results"] = runCleanUp(fetchReviews($argv));
    } catch (Exception $e) {
        $help = helpMessage($help);
    }
} else {
    $message    = "Please ensure you have set the below before using this script";
    $errorArray = array("message" => $message, "parameter" => "");

    $missingParameter = array();

    // Now check if the basic settings are empty and show the end user.
    empty($username) ? $missingParameter[] = "Username":'';
    empty($ticket) ? $missingParameter[] = "Ticket":'';
    empty($swarmURL) ? $missingParameter[] = "SwarmURL":'';

    $errorArray['parameter'] = $missingParameter;

    $help["error"] = $errorArray ;
}
// Output the end result of the what the script does.
echo json_encode($help, JSON_FORCE_OBJECT);
// @codingStandardsIgnoreEnd

Executing the script

The example is written in PHP, and demonstrates how to make use of the APIs which remove unneeded pending changelists. It must be run as a super user.

For a full set of instructions on how to use the example script, see the comments in the script itself.

Abbreviated instructions:

  1. Set the value of the $swarmURL, $username and $ticket variables.

  2. Run the script by using a command similar to the following:

$ php pendingReviewCleanUp.php max=10 author=bruno state=approved