Reviews : Swarm Reviews

Important

Support for APIs older than v9 will be removed in the Swarm 2022.2 release.

Get reviews for action dashboard

Summary

Get reviews for action dashboard

GET /api/v9/dashboards/action

Description

Gets reviews for the action dashboard for the authenticated user.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

Example response

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
}

Example usage

Getting reviews for the action dashboard

To list reviews:

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

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

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
}

Get List of Reviews

Summary

Get List of Reviews

GET /api/v9/reviews/

Description

List and optionally filter reviews.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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.

Reviews are returned in the order they were created in, starting with the most recently created review.

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 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
}
Note

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
}

Example usage

Listing reviews

To list reviews:

curl -u "username:password" "https://my-swarm-host/api/v9/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:

HTTP/1.1 200 OK

{
  "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/v9/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:

HTTP/1.1 200 OK

{
  "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/v9/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:

HTTP/1.1 200 OK

{
  "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:

HTTP/1.1 200 OK

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

Finding inactive reviews (by checking the last updated date)

curl -u "username:password" "https://my-swarm-host/api/v9/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:

HTTP/1.1 200 OK

{
  "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/v9/reviews?max=2&fields=id,changes,description,author,state&hasVoted=up"

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

HTTP/1.1 200 OK

{
  "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/v9/reviews?max=2&fields=id,changes,description,author,state&myComments=true"

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

HTTP/1.1 200 OK

{
  "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:

HTTP/1.1 200 OK

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

Get Review Information

Summary

Get Review Information

GET /api/v9/reviews/{id}

Description

Retrieve information about a review.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Example usage

Fetching a review

To fetch a review:

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

Swarm responds with a review entity:

HTTP/1.1 200 OK

{
  "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": [
      {
        "difference": 1,
        "stream": "//jam/main",
        "streamSpecDifference": 0,
        "change": 124,
        "user": "bruno",
        "time": 1568115902,
        "pending": true,
        "addChangeMode": "replace",
        "testRuns": [
          8
        ]
      },
      {
        "difference": 1,
        "stream": "//jam/main", 
        "streamSpecDifference": 0,
        "change": 12157,
        "user": "bruno",
        "time": 1568115918,
        "pending": true,
        "addChangeMode": "replace",
        "archiveChange": 122,
        "testRuns": [
          1,
          2,
          3,
          4,
          5,
          6,
          7
        ]
      }
    ]
  }
}

Fetching a review that does not exist

If you try to fetch a review that does not exist:

curl -u "username:password" "https://my-swarm-host/api/v9/reviews/999999"

Swarm responds with a 404 resonse:

HTTP/1.1 404 Not Found

{
  "error": "Not Found"
}

Get transitions for a review

Summary

Get transitions for a review

GET /api/v9/reviews/{id}/transitions

Description

Get the allowed transitions for a review.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

Parameters

Parameter Description Type Parameter Type Required

upVoters

A list of users whose vote up will be assumed when determining the transitions. For example if a user has not yet voted but would be the last required vote and asked for possible transitions we would want to include 'approve'

string

query

No

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "isValid": "true",
  "transitions": {
      "needsRevision": "Needs Revision",
      "approved": "Approve",
      "approved:commit": "Approve and Commit",
      "rejected": "Reject",
      "archived": "Archive"
  }
}

Example usage

Getting transitions that a review with id 1 can transition to:

curl -u "username:password" "https://my-swarm-host/api/v9/reviews/1/transitions?upVoters=bruno"

The transitions that are returned depend on the current review state, Swarm setup and the configuration of associated projects and branches

HTTP/1.1 200 OK

{
  "isValid": "true"
  "transitions": {
      "needsRevision": "Needs Revision",
      "approved": "Approve",
      "approved:commit": "Approve and Commit",
      "rejected": "Reject",
      "archived": "Archive"
  }
}

Create a Review

Summary

Create a Review

POST /api/v9/reviews/

Description

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Example response

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
  }
}

Example usage

Starting a review

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

curl -u "username:password" \
     -X POST \
     -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/v9/reviews/"

Swarm responds with the new review entity:

HTTP/1.1 200 OK

{
  "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": []
  }
}

Archiving the inactive reviews

Summary

Archiving the inactive reviews (v6+)

POST /api/v9/reviews/archive/

Description

Archiving reviews not updated since the date (v6+).

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Example response

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": []
}

Example usage

Archiving reviews inactive since 2016/06/30

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

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

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

HTTP/1.1 200 OK

{
  "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:

HTTP/1.1 200 OK

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

Add Change to Review

Summary

Add Change to Review

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

Description

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

Parameters

Parameter Description Type Parameter Type Required Default Value

id

Review ID

integer

path

Yes

 

change

Change ID

integer

form

Yes

 

mode

The mode of operation, currently 'replace' or 'append'

string

form

No

replace

Example response

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
  }
}

Example usage

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 replace a changelist:

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

To append a changelist:

curl -u "username:password" -X POST -d "change=124" -d "mode=append" https://my-swarm-host/api/v9/reviews/123/changes/"

Swarm responds with the updated review entity:

HTTP/1.1 200 OK

{
  "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
      }
    ]
  }
}

Clean up a review

Summary

Clean up a review (v6+)

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

Description

Clean up a review for the given id.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Example response

Successful Response:

HTTP/1.1 200 OK

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

Example usage

Cleaning up a review with id 1

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

curl -u "username:password" \
     -X POST \
     -d "reopen=true" \
     "https://my-swarm-host/api/v9/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:

HTTP/1.1 200 OK

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

Obliterate a review

Summary

Obliterate a review

POST /api/v9/reviews/{id}/obliterate

Description

Obliterate a review for the given id.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "isValid": true,
  "message": "The review with id [1] has been obliterated.",
  "code": 200
}

Example usage

Obliterating a review with id 1

Obliterating review number 1.

curl -u "username:password" \
     -X POST \
     "https://my-swarm-host/api/v9/reviews/1/obliterate"

Swarm responds with a message informing you that is has successfully Obliterated the review:

HTTP/1.1 200 OK

{
  "isValid": true,
  "message": "The review with id [1] has been obliterated.",
  "code": 200
}

Set vote for the authenticated user to up, down, or cleared

Summary

Set the vote for the authenticated user to be up, down or cleared

POST /api/v9/reviews/{id}/vote/

Description

Set the vote for the authenticated user to be up, down or clear.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

Parameters

Parameter Description Type Parameter Type Required

version

Expected to be a valid review version to vote on if supplied, ignored if the version does not exist and the vote will apply to the latest version

string

form

No

vote

Expected to be a valid vote. Valid votes are 'up', 'down' and 'clear

string

form

Yes

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "isValid": "true",
  "messages": ["User username set vote to up on review 1"]
}

Example usage

Voting up for review with id 1

curl -u "username:password" \
     -X POST \
     -d "vote[value]=up" -d "vote[version]=1" \
     "https://my-swarm-host/api/v9/reviews/1/vote/" 

Swarm responds with

HTTP/1.1 200 OK

{
  "isValid": "true",
  "messages": ["User username set vote to up on review 1"]
}

Transition the Review State

Summary

Transition the Review State (v2+)

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

Description

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Example 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
}

Example usage

Committing a review

To commit a review:

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

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

HTTP/1.1 200 OK

{
  "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"
    }
}

Update Review Description

Summary

Update Review Description

PATCH /api/v9/reviews/{review_id}

Description

Update the description field of a review.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
  • Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Example 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
}
Note

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
}