Reviews : Swarm Reviews
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.
- 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.
- 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 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 |
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 |
boolean |
query |
No |
|
ids[] |
One or more review IDs to fetch. Only the specified reviews are returned. This filter cannot be combined with the |
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 |
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
}
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¬UpdatedSince=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.
- 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.
- 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.
- 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+).
- 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.
- 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.
- 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.
- 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.
- 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+).
- 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 |
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.
- 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
}
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
}