API ReferenceContext Repository
Decide several staged ops
Approves or rejects the named ops together, as one decision.
POST /context/v1/changeset/decisions
Approves or rejects the named ops together, as one decision. Name every op of each review item you include: naming only part of an item is a 409, and nothing is widened for you. Use it to settle exactly the ops you reviewed; use POST changeset/decide-outstanding only when you mean to decide everything undecided, including ops other people staged. Same rules and responses as deciding one op.
Requires the context:review scope.
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. |
op_ids | array of string | yes | The ops to decide together, as GET changeset lists them. Name every op of a review item or none of it. |
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. |
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,
"op_ids": [
"csop_example"
]
}curl -sS -X POST "$API_URL/context/v1/changeset/decisions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @body.json