From ab89853169895b17ca81e6eb1a3a2f5e454d90b5 Mon Sep 17 00:00:00 2001 From: rodrigozhou Date: Tue, 24 Sep 2024 12:33:26 -0500 Subject: [PATCH] Add Link spec --- SPEC.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index dbe1ed4..ab8a074 100644 --- a/SPEC.md +++ b/SPEC.md @@ -97,6 +97,10 @@ Headers that start with the `Nexus-Callback-` prefix are expected to be attached the handler. The callback request must strip away the `Nexus-Callback-` prefix. E.g if a Start Operation request includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. +The header `Nexus-Link` contains a `Link` object. The handler can use it to associate resources from the caller to the +operations. You can pass multiple `Nexus-Link` header to send multiple links. See the [Links][#Links] section for more +details. + #### Request Body The body may contain arbitrary data. Headers should specify content type and encoding. @@ -111,11 +115,13 @@ The body may contain arbitrary data. Headers should specify content type and enc **Body**: Arbitrary data conveying the operation's result. Headers should specify content type and encoding. -- `201 Created`: Operation was started and will complete asynchronously. +- `201 Created`: Operation was started and will complete asynchronously. It may return `Nexus-Link` headers to associate + resources to this operation. **Headers**: - `Content-Type: application/json` + - `Nexus-Link: ; type="..."` **Body**: A JSON serialized [`OperationInfo`](#operationinfo) object. @@ -264,6 +270,31 @@ following predefined error codes. | `UNAVAILABLE` | 503 | The service is currently unavailable. | | `UPSTREAM_TIMEOUT` | 520 | Used by gateways to report that a request to an upstream server has timed out. | +## Links + +The `Link` object represents a link to which the receiver can use and associate the operation. +The object MUST adhere to the given schema: + +```yaml +type: object +properties: + url: + type: url + description: | + The URL the link is pointing to. + + type: + type: string + description: | + Type provides additional information about the URL that can be used to parse it. +``` + +The `Nexus-Link` header field provides a means for serializing one or more `Link` objects in HTTP headers. This header +is encoded the same way as the HTTP header `Link` described [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link). + +Handlers and callers can specify links in different Nexus requests/responses to associate an operation with arbitrary +resources. + ## General Purpose Headers ### `Request-Timeout`