diff --git a/SPEC.md b/SPEC.md index 76fac6a..9bfcba3 100644 --- a/SPEC.md +++ b/SPEC.md @@ -17,10 +17,14 @@ An operation is addressed using the following components: - The containing endpoint, a URL prefix (e.g. `http://api.mycompany.com/services/`) - Service Name - A grouping of operations (e.g. `payments.v1`) - Operation Name - A unique name for the given (e.g. `charge`) -- Operation ID - A unique ID assigned by the handler as a response to a [StartOperation](#start-operation) request. +- Operation Token - A unique token assigned by the handler as a response to a [StartOperation](#start-operation) + request. -The service name, operation name, and operation ID MUST not be empty and may contain any arbitrary character sequence as -long as they're encoded into the URL. +The service name and operation name MUST not be empty and may contain any arbitrary character sequence as long as +they're encoded into the URL. + +An operation token MUST not be empty and contain only characters that are valid HTTP header values. When passing a token +as part of a URL path make sure any special characters are encoded. ## Schema Definitions @@ -57,10 +61,10 @@ The `OperationInfo` object MUST adhere to the given schema: ```yaml type: object properties: - id: + token: type: string description: | - An identifier for referencing this operation. + A token for referencing this operation. state: enum: @@ -150,17 +154,27 @@ The body may contain arbitrary data. Headers should specify content type and enc Request to cancel an operation. The operation may later complete as canceled or any other outcome. Handlers should ignore multiple cancelations of the same operation and return successfully if cancelation was already requested. -**Path**: `/{service}/{operation}/{operation_id}/cancel` +**Path**: `/{service}/{operation}/cancel` **Method**: `POST` +#### Request Headers + +The operation token received as a response to the Start Operation method. Must be delivered either via the `token` query +param or the `Nexus-Operation-Token` header field. + +#### Query Parameters + +- `token`: The operation token received as a response to the Start Operation method. Must be delivered either via the + `token` query param or the `Nexus-Operation-Token` header field. + #### Response Codes - `202 Accepted`: Cancelation request accepted. **Body**: Empty. -- `404 Not Found`: Operation ID not recognized or references deleted. +- `404 Not Found`: Operation token not recognized or references deleted. **Headers**: @@ -172,12 +186,20 @@ ignore multiple cancelations of the same operation and return successfully if ca Retrieve operation result. -**Path**: `/{service}/{operation}/{operation_id}/result` +**Path**: `/{service}/{operation}/result` **Method**: `GET` +#### Request Headers + +The operation token received as a response to the Start Operation method. Must be delivered either via the `token` query +param or the `Nexus-Operation-Token` header field. + #### Query Parameters +- `token`: The operation token received as a response to the Start Operation method. Must be delivered either via the + `token` query param or the `Nexus-Operation-Token` header field. + - `wait`: Optional. Duration indicating the waiting period for a result, defaulting to no wait. If by the end of the wait period the operation is still running, the request should resolve with a 412 status code (see below). @@ -217,7 +239,7 @@ Retrieve operation result. **Body**: A JSON serialized [`Failure`](#failure) object. -- `404 Not Found`: Operation ID not recognized or references deleted. +- `404 Not Found`: Operation token not recognized or references deleted. **Headers**: @@ -229,10 +251,20 @@ Retrieve operation result. Retrieve operation details. -**Path**: `/{service}/{operation}/{operation_id}` +**Path**: `/{service}/{operation}` **Method**: `GET` +#### Request Headers + +The operation token received as a response to the Start Operation method. Must be delivered either via the `token` query +param or the `Nexus-Operation-Token` header field. + +#### Query Parameters + +- `token`: The operation token received as a response to the Start Operation method. Must be delivered either via the + `token` query param or the `Nexus-Operation-Token` header field. + #### Response Codes - `200 OK`: Successfully retrieved info. @@ -245,7 +277,7 @@ Retrieve operation details. A JSON serialized [`OperationInfo`](#operationinfo) object. -- `404 Not Found`: Operation ID not recognized or references deleted. +- `404 Not Found`: Operation token not recognized or references deleted. **Headers**: @@ -312,7 +344,7 @@ For invoking a callback URL: - Issue a POST request to the caller-provided URL. - Include any callback headers supplied in the originating StartOperation request, stripping away the `Nexus-Callback-` prefix. -- Include the `Nexus-Operation-Id` header, `Nexus-Operation-Start-Time` and any `Nexus-Link` headers for resources +- Include the `Nexus-Operation-Token` header, `Nexus-Operation-Start-Time` and any `Nexus-Link` headers for resources associated with this operation to support completing asynchronous operations before the response to StartOperation is received. `Nexus-Operation-Start-Time` should be in a valid HTTP format described [here](https://www.rfc-editor.org/rfc/rfc5322.html#section-3.3). If is omitted, the time the completion is received