API Endpoints // Swarm 2014.3: User Guide

Activity : Swarm Activity List

POST /api/v1/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, e.g., 'jira'	string	form	Yes
user	User who performed the action	string	form	Yes
action	Action that was performed - post-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

Example of a 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": "coffee",
    "user": "A dingo"
  }
}

Projects : Swarm Projects

GET /api/v1/projects/

Summary: Get List of Projects

Description

Returns the complete list of projects in Swarm.

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 will show all fields.	string	query	No

Example of a successful response

HTTP/1.1 200 OK

{
  "projects": [
    {
      "id": "testproject",
      "branches": [
        {
          "id": "main",
          "name": "main",
          "paths": ["//depot/main/TestProject/..."],
          "moderators": []
        }
      ],
      "deleted": false,
      "deploy": {"url": "", "enabled": false},
      "description": "Test test test",
      "followers": [],
      "jobview": "subsystem=testproject",
      "members": ["alice"],
      "name": "TestProject",
      "tests": {"url": "", "enabled": false}
    }
  ]
}

Index : Basic API controller providing a simple version action

GET /api/v1/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.

Example of a successful response

HTTP/1.1 200 OK

{
    "year": "2014",
    "version": "SWARM/2014.3-MAIN/885869 (2014/06/25)"
}

Note

Note: "year" refers to the year of the Swarm release, not necessarily the current year.

Reviews : Swarm Reviews

GET /api/v1/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 will show all fields.	string	query	No

Example of a 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": []
    },
    "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 of a failure response

HTTP/1.1 404 Not Found

{
  "error": "Not Found"
}

POST /api/v1/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

Example of a 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": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}

POST /api/v1/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

Example of a successful response

HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "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
  }
}

GET /api/v1/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 will be 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 will be returned. It does guarantee 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 will show all fields.	string	query	No
change[]	One or more change IDs to limit reviews by. Reviews associated with any of the specified changes will be returned.	array (of integers)	query	No
hasReviewers	Boolean option to limit to reviews to those with or without reviewers. Use 'true' or '1' for true and 'false' or '0' for false. The presence of the parameter without a value will be evaluated as true.	boolean	query	No
ids[]	One or more review IDs to fetch. Only the specified reviews will be 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 will be returned.	string	query	No
participants[]	One or more participants to limit reviews by. Reviews with any of the specified participants will be returned.	array (of strings)	query	No
project[]	One or more projects to limit reviews by. Reviews affecting any of the specified projects will be returned.	array (of strings)	query	No
state[]	One or more states to limit reviews by. Reviews in any of the specified states will be returned.	array (of strings)	query	No
passesTests	Boolean option to limit reviews by tests passing or failing. Use 'true' or '1' for true and 'false' or '0' for false. The presence of the parameter without a value will be evaluated as true.	string	query	No

Examples of successful responses

HTTP/1.1 200 OK

{
  "lastSeen": 12206,
  "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
}

Note

Swarm will return "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.

HTTP/1.1 200 OK

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