Decide one staged op
Approves or rejects one op of the open changeset, or returns it to undecided.
POST /context/v1/changeset/ops/{op_id}/decision
Approves or rejects one op of the open changeset, or returns it to undecided. Only approved ops are published by a merge. Rejecting an op also rejects every op that depends on it, listed in cascaded_op_ids. Approving an op whose dependency is rejected or undecided is a 409 naming it. The ops of one asset, or of one relationship, are one review item, and naming one op here decides every op of its item (decided_op_ids lists them all). To decide exactly the ops you name, use POST changeset/decisions, which refuses an item you name only part of. Send expected_revision so a decision never lands on a changeset that moved after you read it. Needs the review scope, which a key that can only stage does not hold.
Requires the context:review scope.
Parameters
| Parameter | Location | Required | Description |
|---|---|---|---|
op_id | path | yes | The id of the op, as GET changeset lists it. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
decision | string, one of approved, rejected, undecided | yes | approved or rejected; undecided returns one op to review (it is refused when deciding every undecided op). |
expected_revision | integer or null | no | The changeset revision you were looking at. When it has moved the call is a 409, so a decision never lands on something you did not see. |
provenance | object or null | no | Who decided and why, for the revision journal. Omit to have it filled in from the key. |
reason | string or null | no | Why, kept with the decision. Worth giving for a rejection. |
Responses
| Status | Meaning |
|---|---|
200 | The request succeeded. |
401 | The token is missing, expired or invalid. |
403 | The token does not carry the scope this operation requires. |
404 | No such project, or the token belongs to a different project. |
422 | The request was not valid: a parameter or the body failed validation. |
The 200 response body:
| Field | Type | Required | Description |
|---|---|---|---|
cascaded_op_ids | array of string | yes | Ops rejected because they depend on an op this call rejected. |
changeset | ChangesetRecord | yes | The open changeset as it stands after the decision. |
decided_op_ids | array of string | yes | The ops whose decision this call changed. |
Shapes
The named shapes used above.
ChangesetRecord
The open changeset: the proposed change and where review stands.
| Field | Type | Required | Description |
|---|---|---|---|
base_release | integer | yes | The release the changeset was opened against. Send it back when staging. |
base_repository_revision | string | yes | A fingerprint of the repository state the changeset was opened against. |
changeset_id | string | yes | The changeset's id. |
decision_summary | DecisionSummary | yes | How many ops have been decided. |
invalidated_by_release | integer or null | no | The release that made this changeset impossible to merge, if one did. |
merge_claimed_at | string or null | no | When a publication claimed the changeset, while one is in progress. |
next_seq | integer | yes | The position the next staged op will take. |
opened_at | string | yes | When the changeset was opened. |
opened_by | object | yes | Who opened it and why. |
ops | array of ChangesetOp | yes | Every op staged so far, in order. |
project_id | string | yes | The project the changeset belongs to. |
published_release | integer or null | no | The release it produced, once published. |
revision | integer | yes | The changeset's revision. It changes every time the changeset does; send it back when staging. |
settled_at | string or null | no | When it was published or abandoned. |
settled_by | object or null | no | Who settled it. |
status | string | yes | Whether the changeset is open or how it was settled. |
superseded_op_ids | array of string | yes | Ops that a later op overwrote. |
DecisionSummary
How many ops review has decided.
| Field | Type | Required | Description |
|---|---|---|---|
approved | integer | yes | Ops approved. |
rejected | integer | yes | Ops rejected. |
undecided | integer | yes | Ops still waiting for a decision. |
ChangesetOp
One staged op and what has been decided about it.
| Field | Type | Required | Description |
|---|---|---|---|
carried_from | string or null | no | The changeset the op was carried over from, if it was. |
carried_to | string or null | no | The changeset the op was carried over to, if it was. |
cascaded_from | string or null | no | The op whose rejection caused this one to be rejected, if any. |
conflict | string or null | no | Why the op cannot merge as it stands, when something it depends on has moved; null otherwise. |
decided_at | string or null | no | When it was decided. |
decided_by | object or null | no | Who decided and why, once someone has; null while the op is undecided. |
decision | string | yes | Where review stands: undecided, approved or rejected. |
decision_history | array of object | yes | Every decision made about the op, oldest first. |
op | object | yes | The op as it was sent; its op field names the kind. GET changeset leaves out an upsert's content and the value of a patch's edit, which GET changeset/ops returns. |
op_id | string | yes | The id the service assigned when the op was staged. Use it to remove the op. |
reason | string or null | no | The reason given for a rejection. |
review_key | string | yes | Groups the ops a reviewer decides together. |
seq | integer | yes | The op's position in the changeset, in staging order. |
staged_at | string | yes | When the op was staged. |
staged_by | object | yes | Who staged it and why. |
status | string | yes | The op's state in the changeset. |
Example
A request body (ids and values are placeholders), saved as body.json:
{
"decision": "approved",
"expected_revision": 3
}curl -sS -X POST "$API_URL/context/v1/changeset/ops/$OP_ID/decision" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @body.json