Helix Swarm Guide (2019.3)

Changes : API controller providing a service for changes

Important

From Swarm 2019.3, APIs older than v9 are being deprecated. Support for them will be removed in a future release.

Get projects and branches affected by a given change id

Summary

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

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

Description

All authenticated users are able to use this API.

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.

Example response

Successful Response:

HTTP/1.1 200 OK

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

Get default reviewers for a given change id

Summary

Get default reviewers for a given change id.

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

Description

All authenticated users are able to use this API.

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.

Example response

Successful Response:

HTTP/1.1 200 OK

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

Perform checks on a change if enabled

Summary

Performs checks on the change if enabled

GET /api/v9/changes/{id}/check

Description

Performs checks on the change if workflow configuration requires it.

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.

Parameters

Parameter Description Type Parameter Type Required

id

Change to check

string

form

Yes

type

The type of check. Must have a value of enforced, strict or shelve

string

form

Yes

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "status":   "OK",
  "isValid":  "true",
  "messages": []
}

Examples of usage

Carry out enforced checks on a change if configured

To check change 42:

curl -u "username:password" "https://my-swarm-host/api/v9/changes/42/check?type=enforced"

JSON Response:

HTTP/1.1 200 OK

{
  "status":   "OK",
  "isValid":  "true",
  "messages": []
}

Carry out enforced checks on a change if configured. Example of a failed 'requires review'

To check change 42:

curl -u "username:password" "https://my-swarm-host/api/v9/changes/42/check?type=enforced"

JSON Response:

HTTP/1.1 200 OK

{
  "status":   "NO_REVIEW",
  "isValid":  "false",
  "messages": ["Change [42] must be associated with a review"]
}

Carry out strict checks on a change if configured

To check change 42:

curl -u "username:password" "https://my-swarm-host/api/v9/changes/42/check?type=strict"

JSON Response:

HTTP/1.1 200 OK

{
  "status":   "OK",
  "isValid":  "true",
  "messages": []
}