Rename operation ID to token (#16)

Rename operation ID to token to clarify that it is meant to be opaque. Tokens may be encrypted, signed, and used as OTPs.

Also remove the operation ID from the request paths and accept the token as either a query param or a header.

Author: bergundy

Diff for: 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