Reviews: Swarm reviews
Get a list of reviews
Summary
Get a list of reviews.
GET /api/v10/reviews
Description
List the reviews the user has permission to view.
- 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 |
---|---|---|---|---|
max |
Specify the maximum number of results to return as an integer greater than 0. If the max parameter is not specified, the 50 most recent reviews are returned. |
integer |
query |
No |
project |
To limit the results to a list of reviews in a specific project or projects, specify the projects you want reviews returned for. |
string |
query |
No |
after |
Return reviews created after the reviewid specified in the after parameter. Reviews are returned in the order they were created in. Note
You cannot use the after and afterUpdated parameters in the same request, they are mutually exclusive. |
string |
query |
No |
afterUpdated |
Return reviews updated on the day before the date/time specified in the afterUpdated parameter. The parameter value must be set in seconds since epoch. The seconds since epoch value for the day reviews are returned for is included at the end of the response. Reviews are returned in the order they were updated in, most recent first. Used by the Swarm team to step backwards one day at a time, loading reviews in an iterative process by using the value returned in a response as the afterUpdated parameter value for the next request. For example:
Note
You cannot use the after and afterUpdated parameters in the same request, they are mutually exclusive. |
string |
query |
No |
state |
To limit the results to a list of reviews in a specific state or states, specify the states you want reviews returned for. Valid review states are:
|
string |
query |
No |
Example usage
Get a list of reviews
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews"
Swarm responds with the review entities:
By default, this is limited to the 50 most recent reviews. This can be changed by adding a max parameter value to the request.
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12344,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 1,
"lastSeen": 12345
}
}
Get a list of the 25 most recent reviews
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?max=25"
Swarm responds with the 25 most recent review entities:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12344,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 1,
"lastSeen": 12345
}
}
Get a list of reviews for the myproject project
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?project=myproject"
Swarm responds with the review entities for the myproject project:
By default, this is limited to the 50 most recent reviews. This can be changed by adding a max parameter value to the request.
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12344,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 1,
"lastSeen": 12345
}
}
Get a list of reviews for the myproject and gemini projects
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?project[]=myproject&project[]=gemini"
Swarm responds with the review entities for the myproject and gemini projects:
By default, this is limited to the 50 most recent reviews. This can be changed by adding a max parameter value to the request.
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12344,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
"id": 12356,
"type": "default",
"changes": [
12350,
],
"commits": [],
"author": "jsmith",
"approvals": null,
"participants": ["jsmith"],
"participantsData": {
"jsmith": []
},
"hasReviewer": 0,
"description": "Another one of my reviews",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"gemini": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "pass",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 2,
"lastSeen": 12356
}
}
Get a list of reviews created after review 12344
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?after=12344"
Swarm responds with the review entities:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12345,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 7,
"lastSeen": 12352
}
}
Get a list of reviews updated during the day before the set date
Request reviews updated on the day before 1606233362 (Tuesday November 24th, 2020, 15:56:02)
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?afterUpdated=1606233362"
Swarm return all reviews that were updated on the day before the date/time specified in your request. In this example, Swarm responds with any reviews that were updated on Monday November 23rd 2020. The seconds since epoch value Swarm used is added to the end of the response:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12345,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1606119044,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 25,
"lastSeen": "0",
"afterUpdated": "1606089600"
}
}
Get a list of reviews that need review
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?state=needsReview"
Swarm responds with the review entities in the needsReview state:
By default, this is limited to the 50 most recent reviews. This can be changed by adding a max parameter value to the request.
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12344,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 1,
"lastSeen": 12345
}
}
Get a list of reviews that are open
Reviews are considered open when they are in any one of three states:
- needsReview
- needsRevision
- approved:isPending
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews?state[]=approved:isPending&state[]=needsReview&state[]=needsRevision"
Swarm responds with the review entities for open reviews:
By default, this is limited to the 50 most recent reviews. This can be changed by adding a max parameter value to the request.
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [
12344,
],
"commits": [],
"author": "bruno",
"approvals": null,
"participants": ["bruno"],
"participantsData": {
"bruno": []
},
"hasReviewer": 0,
"description": "Review for my code change",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"myproject": ["main"]
},
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": "fail",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
"id": 12356,
"type": "default",
"changes": [
12350,
],
"commits": [],
"author": "jsmith",
"approvals": null,
"participants": ["jsmith"],
"participantsData": {
"jsmith": []
},
"hasReviewer": 0,
"description": "Another one of my reviews",
"created": 1594265070,
"updated": 1594266228,
"projects": {
"gemini": ["main"]
},
"state": "needsRevision",
"stateLabel": "Needs Revision",
"testStatus": "pass",
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"complexity": {
"files_modified": 1,
"lines_added": 0,
"lines_edited": 1,
"lines_deleted": 0
},
},
...
<other review ids formatted as above>
...
],
"totalCount": 2,
"lastSeen": 12356
}
}
If a request fails
<error code>:
- 400 the input specified must be an integer greater than 0
- 401 you are not authorized to view reviews
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Get review information
Summary
Get review information and metadata.
GET /api/v10/reviews/{id}
Description
Retrieve all of the information and metadata 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 |
---|---|---|---|---|
id |
Review ID |
integer |
path |
Yes |
transitions |
To limit the results to a list of the state transitions that are allowed for the review, add the transitions parameter to the request. |
query | path | No |
Example usage
Fetch information for review number 12345
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345"
Swarm responds with a review entity:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [1,3],
"commits": [],
"author": "normal-user",
"approvals": null,
"participants": ["normal-user"],
"participantsData": {
"normal-user": []
},
"hasReviewer": 0,
"description": "Added a file\n",
"created": 1576595749,
"updated": 1576595754,
"projects": [],
"state": "needsReview",
"stateLabel": "Needs Review",
"transitions": {
"needsRevision": "Needs Revision",
"approved": "Approve",
"approved:commit": "Approve and Commit",
"rejected": "Reject",
"archived": "Archive"
},
"testStatus": null,
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": [],
"versions": [
{
"difference": 1,
"stream": "//jam/main",
"streamSpecDifference": 0,
"change": 2,
"user": "normal-user",
"time": 1576595752,
"pending": true,
"addChangeMode": "replace",
"archiveChange": 3,
"testRuns": [}
},
{
...
<other "versions" formatted as above>
...
}
],
"description-markdown": "<span class=\"first-line\">Added a file</span>"
}]
}
}
Fetch a list of the state transitions that are allowed for review 12345
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345/transitions"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"transitions": {
"needsRevision": "Needs Revision",
"approved": "Approve",
"approved:commit": "Approve and Commit",
"rejected": "Reject",
"archived": "Archive"
}
}
}
If a request fails
<error code>:
404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Get list of files that changed in a review
Summary
Get a list of files that changed between specified versions of a review.
GET /api/v10/reviews/{id}/files?from={x}&to={y}
Description
Get a list of files that changed between specified versions of a review.
The GET request returns the following:
- root: the common root depot path of the files that changed between the specified versions of the review.
- limited: Swarm limits the number of files presented for changelists based on the max_changelist_files setting for the Helix server connection. By default, a maximum of 1000 files are returned:
- true: the number of files in the review is ≥ max_changelist_files. Some of the files changed in the specified review versions might not have been returned by this request.
- false: the number of files in the review is < max_changelist_files. All of the files changed in the specified review versions have been returned by this request.
- For each file:
- depotFile: the filename and path of the file.
- action: how the file changed, Add, Edit, or Delete.
- type: the filetype of the file, text, binary, symlink, unicode, utf8, utf16, apple, or resource.
- rev: the file revision number.
- fileSize: the file size in bytes.
- digest: the file digest.
For more information on filetypes, see the Base filetypes section of the Helix Core P4 Command Reference.
- 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 |
from |
Specify a value for from:
|
integer |
query |
No |
to |
Specify a value for to:
|
integer |
query |
No |
Example usage
Get a list of files that changed between version 1 and 3 of review 12345
curl -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345/files?from=1&to=3"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"root": "//jam/main/src",
"limited": false,
"files": [{
"depotFile": "//jam/main/src/execvms.c",
"action": "edit",
"type": "text",
"rev": "3",
"fileSize": "3343",
"digest": "82D5161601D12DB46F184D3F0778A16D"
},
{
"depotFile": "//jam/main/src/jam.h",
"action": "add",
"type": "text",
"rev": "2",
"fileSize": "7364",
"digest": "2E94B379F201AD02CF7E8EE33FB7DA99"
}
]
}
}
If a request fails
<error code>:
- 400 invalid review version number requested
- 403 Insufficient permissions to access the review
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Set vote for the authenticated user
Summary
Set the vote for the authenticated user to be up, down, or cleared
POST /api/v10/reviews/{id}/vote
Description
Set the vote for the authenticated user to be up, down, or cleared.
- 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 |
vote |
Specify the vote value you want to set on the review. Valid vote values are up, down, and clear. If the requested vote value already exists on the latest version of the review, the vote is not changed. |
string | body | Yes |
|
Votes can only be set on the latest version of a review. The version parameter is used to check that you are voting on the latest version of the review. If the specified version is not the latest version of the review, the vote is not applied to the review and a 400 error is returned. If the version parameter is not included, the vote is applied to the latest version of the review. |
integer |
body |
No |
Example usage
Vote up version 1 of review 12345
curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/vote"
The "mybodyfilename.txt" file contains the authenticated user's vote and the version of the review they are voting on:
{
"vote": "up"
"version": "1"
}
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"vote": {
"value": 1,
"version": 1,
"isStale": false
}
}
}
If a request fails
<error code>:
- 400 Version specified is not the latest version of the review
- 401 User must be authenticated
- 403 Insufficient permissions to access the review
- 404 Review does not exist
- 409 Invalid vote specified, the response error message lists valid votes.
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Change review state
Summary
Change the state of a review.
POST /api/v10/reviews/{id}/transition
Description
Change the state of a review. The state that a review can be changed to depends on a number of factors including its current state. You can check that the state change you want to make is allowed for the review by making a Get review information request first. For more information on review states and restrictions on changing them, see States
Review state transitions:
- needsRevision
- needsReview
- approved only available if the voting requirements for the review are satisfied
- committed only available for Pre-commit model reviews that have been approved
- approved:commit only available for unapproved Pre-commit model reviews when the voting requirements for the review are satisfied
- rejected
- archived
- 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 |
Example usage
Change the state of review 12345 to approved
curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/transition"
The "mybodyfilename.txt" file contains the state you want to change the review to:
{
"transition": "approved"
}
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"state": "approved",
"stateLabel": "Approved"
}
}
If a request fails
<error code>:
- 400 Specified review state does not exist
- 401 Insufficient permissions to change review state
- 403 Insufficient permissions to access the review
- 404 Review does not exist
- 409 Specified state is not a valid transition for this review. API response message lists all valid transition states for the review
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Change review author
Summary
Change review author.
PUT /api/v10/reviews/{id}/author
Description
Change the review author.
By default you cannot change the author of a review, this option must be enabled by your Swarm administrator. See Allow author change for details.
- 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 |
Example usage
Change the author of review 12345
curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/author"
The "mybodyfilename.txt" file contains the new author username:
{
"author": "asmith"
}
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"author": "asmith"
}
}
If a request fails
<error code>:
- 400 Author change not allowed, set allow_author_change to true
- 401 Insufficient permissions to change author
- 403 Insufficient permissions to access the review
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Replace review description
Summary
Replace review description.
PUT /api/v10/reviews/{id}/description
Description
Replace the review description with a new description.
Optional: also replace pending changelist description
Only available if you are editing the description of a pre-commit review and you are the original author of the changelist that created the review.
To also apply your review description changes to the original changelist description, specify 'updateOriginalChangelist' : true.
- 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 |
Example usage
Replace the description for review 12345
curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/description"
The "mybodyfilename.txt" file contains the new description:
{
"description": "This is my replacement description text and it is better than the original description."
}
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"description": "This is my replacement description text and it is better than the original description.",
"description-markdown": "<span class=\"first-line\">This is my replacement description text and it is better than the original description.</span>"
}
}
If a request fails
<error code>:
- 401 Insufficient permissions to change description
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Replace review participants
Summary
Replace review participants.
PUT /api/v10/reviews/{id}/participants
Description
Replace the review participants with a new set of participants.
- The text file used for your request must contain a complete list of all of the participants you want on the review (users and groups). The existing review participants are completely replaced by the participants in the text file. For example, if you already have some group participants on the review and you do not specify any group roles in the text file, all of the participant groups will be removed from the review.
-
Default reviewers can be removed from a review but retained default reviewers cannot be removed from a review, see Default reviewers and Retain default reviewers.
If your request tries to remove a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been removed.
- You cannot reduce the voting requirement of a retained default reviewer but you can increase it, see Retain default reviewers.
If your request tries to reduce the voting requirement of a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been changed.
- 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 |
Example usage
Replace participants for review 12345
curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/participants"
The "mybodyfilename.txt" file contains the new review participants and their voting requirements:
{
"participants": {
"users": {
"asmith": {
"required": "yes"
},
"jbloggs": {
"required": "no"
},
"molsen": {
"required": "no"
}
},
"groups": {
"docs": {
"required": "none"
},
"qa": {
"required": "all"
},
"dev": {
"required": "one"
},
"testers": {
"required": "one"
}
}
}
}
Swarm responds with a list of all of the participants and their voting requirements:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"combinedReviewers": [
"'molsen' must be a reviewer with a minimum requirement of 'required'",
"'testers' must be a reviewer with a minimum requirement of 'require all'"
]
},
"data": {
"participants": {
"users": {
"asmith": {
"required": "yes"
},
"jbloggs": {
"required": "no"
},
"molsen": {
"required": "yes",
"minimumRequired": "yes"
}
},
"groups": {
"dev": {
"required": "one"
},
"docs": {
"required": "none"
},
"qa": {
"required": "all"
},
"testers": {
"required": "all",
"minimumRequired": "all"
}
}
}
}
}
If a request fails
<error code>:
- 400 Invalid participant data, for example: unknown participant id or voting requirement
- 401 Insufficient permissions to replace participants
- 403 Insufficient permissions to edit reviewers
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Append review participants
Summary
Append review participants.
POST /api/v10/reviews/{id}/participants
Description
Append more participants to the existing review participants.
Only the users and groups specified in the request are appended to the review. For example, if you don't want to append any group participants to the review there is no need to include the groups role in the text file.
- 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 |
Example usage
Append participants to review 12345
curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/participants"
The "mybodyfilename.txt" file contains the new review participants and their voting requirements. In this example, bjones is an optional participant:
{
"participants": {
"users": {
"bjones": []
}
}
}
Swarm responds with a list of all of the participants and their voting requirements:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"participants": {
"users": {
"asmith": {
"required": "yes"
},
"jbloggs": {
"required": "no"
},
"molsen": {
"required": "yes",
"minimumRequired": "yes"
},
"bjones": []
},
"groups": {
"dev": {
"required": "one"
},
"docs": {
"required": "none"
},
"qa": {
"required": "all"
},
"testers": {
"required": "all",
"minimumRequired": "all"
}
}
}
}
}
If a request fails
<error code>:
- 400 Invalid participant data, for example: unknown participant id or voting requirement
- 401 Insufficient permissions to append participants
- 403 Insufficient permissions to edit reviewers
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Delete review participants
Summary
Delete review participants.
DELETE /api/v10/reviews/{id}/participants
Description
Delete review participants from a review.
-
Only the users and groups specified in the request are deleted from the review. For example, if you don't want to delete any group participants from the review there is no need to include the groups role in the text file.
-
Default reviewers can be removed from a review but retained default reviewers cannot be removed from a review, see Default reviewers and Retain default reviewers.
If your request tries to remove a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been removed.
- 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 |
Example usage
Delete participants from review 12345
curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/participants"
The "mybodyfilename.txt" file contains the participants you want to delete from the review:
{
"participants": {
"users": {
"jbloggs": [],
"molsen": []
},
"groups": {
"docs": []
}
}
}
Swarm responds with a list of all of the participants and their voting requirements:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"combinedReviewers": [
"'molsen' must be a reviewer with a minimum requirement of 'required'"
]
},
"data": {
"participants": {
"users": {
"asmith": {
"required": "yes"
},
"molsen": {
"required": "yes",
"minimumRequired": "yes"
},
"bjones": []
},
"groups": {
"dev": {
"required": "one"
},
"qa": {
"required": "all"
},
"testers": {
"required": "all",
"minimumRequired": "all"
}
}
}
}
}
If a request fails
<error code>:
- 400 Unknown participant id
- 401 Insufficient permissions to delete participants
- 403 Insufficient permissions to edit reviewers
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Obliterate a review
Summary
Obliterate a review.
DELETE /api/v10/reviews/{id}
Description
Obliterate must be used with care, the review and all of its associated metadata are permanently deleted. An obliterated review cannot be reinstated, not even by Perforce Support.
- By default, you must be a user with admin or super user rights to obliterate a review.
- Optional: Swarm can be configured to allow users to obliterate reviews that they have authored. Configured by your Swarm administrator, see Allow author obliterate review.
Obliterate is used to permanently delete reviews that have been created by mistake. For instance, if a review is associated with the wrong changelist, or a review contains sensitive information that should not be openly available.
For information on what happens to a review when it is obliterated, see When you obliterate 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 |
Example usage
Obliterate review number 12345
curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345"
Swarm responds with a message informing you that it has successfully Obliterated the review:
HTTP/1.1 200 OK
{
"error": null,
"messages": [{
"code": "review-obliterated",
"text": "The review with id [12345] has been obliterated."
}],
"data": {
"reviews": [{
"id": 12345,
"type": "default",
"changes": [1, 3],
"commits": [],
"author": "normal-user",
"approvals": null,
"participants": ["normal-user"],
"participantsData": {
"normal-user": []
},
"hasReviewer": 0,
"description": "Hello\n",
"created": 1576579928,
"updated": 1576579932,
"projects": [],
"state": "needsReview",
"stateLabel": "Needs Review",
"testStatus": null,
"testDetails": [],
"deployStatus": null,
"deployDetails": [],
"pending": true,
"commitStatus": [],
"groups": []
"versions": [
{
"difference": 1,
"stream": "//jam/main",
"streamSpecDifference": 0
"change": 2,
"user": "normal-user",
"time": 1576595752,
"pending": true,
"addChangeMode": "replace",
"archiveChange": 3
"testRuns": []
},
{
...
<other "versions" formatted as above>
...
}
}
}
}
}
Obliterate review number 56789 (with insufficient permission)
curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v10/reviews/56789"
Swarm responds with a message informing you that you do not have permission to obliterate the review:
HTTP/1.1 200 OK
{
"error":403,
"messages":[{
"code": "forbidden-exception",
"text": "Failed to Obliterate the review, you need to have admin privileges or be the review author with 'allow_author_obliterate' set to true."
}]
"data": null
}
If a request fails
<error code>":
- 403 Insufficient permissions to obliterate review
- 404 Review does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}