Updates to align links and callbacks
MODIFY
versions/3.0.md
versions/3.0.md
@@ -1561,38 +1561,26 @@ description: object created
#### <a name="callbackObject"></a>Callback Object
-A map of possible out-of band callbacks related to the parent operation. Each value in the map is an [operation object](#operationObject) that describes a request that may be initiated by the API provider and the responses expected. The key value used to identify callback object is an expression, that when evaluated at runtime, identifies a URL to used for the callback operation.
+A map of possible out-of band callbacks related to the parent operation.
+Each value in the map is an [operation object](#operationObject) that describes a request that may be initiated by the API provider and the expected responses.
+The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
-<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback request and expected responses
+<a name="callbackName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback request and expected responses
This object can be extended with [Specification Extensions](#specificationExtensions).
##### Key Expression
-The key used to identify the callback object is also an expression that can be evaluated on the runtime HTTP request/response to identify the URL to be used for the callback request. A simple example might be "$request.body.url". However, the expression syntax enables accessing the complete HTTP message and reaching into any payload that can map to an object/array/property data model.
+The key used to identify the callback object is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
+A simple example might be "$request.body(/url)".
+However, using [variable substition](#variableSubstition) syntax the complete HTTP message can be accessed.
+This includes accessing any part of a body that can be accessed using a JSONPointer [RFC6901](https://tools.ietf.org/html/rfc6901).
-The expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax
-```
- expression = target source *( "." bind-token [ index ]] )
- target = ("$request." | "$response.")
- source = ( header-reference | query-reference | path-reference | body-reference )
- header-reference = "header." token
- query-reference = "query." name
- path-reference = "path." name
- body-reference = "body" *( index | "." name )
- index = "[" *(digit) "]"
- name = *( char )
- char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7)
- token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)
-```
-
-The `name` identifier is case-sensitive, whereas `token` is not.
-
-Given the following HTTP request:
+For example, given the following HTTP request:
```http
POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
@@ -1618,11 +1606,13 @@ Here are the examples of how the various expressions evaluate, assuming a the ca
Expression | Value
---|:---
+$url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning
+$method | POST
$request.path.eventType | myevent
$request.query.queryUrl | http://clientdomain.com/stillrunning
$request.header.content-Type | application/json
-$request.body.failed | http://clientdomain.com/stillrunning
-$request.body.successurls[2] | http://clientdomain.com/medium
+$request.body(/failed) | http://clientdomain.com/stillrunning
+$request.body(/successurls/2) | http://clientdomain.com/medium
$response.header.Location | http://example.org/subscription/1
@@ -1633,7 +1623,7 @@ A callback to the URL specified by the `url` parameter in the request
```yaml
myWebhook:
- '$request.body.url':
+ '$request.body(/url)':
post:
body:
name: postResponse
@@ -1746,7 +1736,7 @@ Field Name | Type | Description
href | url | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.
operationId | string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values _may_ be used to locate an existing Operation Object in the OAS.
parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
-headers | Link Headers Object | an Object representing headers to pass to the linked resource.
+headers | Link Headers Object | an Object representing headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override.
description | string | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -1757,7 +1747,7 @@ Because of the potential for name clashes, consider the `href` syntax as the pre
#### <a name="responsePayload"></a>Response Payload Values
-Payload values are only available in parseable response payloads which match the advertised media-type.
+Payload values are only available in parseable response payloads which match the advertised media-type and for media-types that can map to the object/array/property model syntax used by variable expressions.
In all cases, if a value does _not_ exist, the parameter will be considered a `null` value (as opposed to an empty value) and _not_ passed as a parameter to the linked resource.
In cases where a value is required, and a parameter is not supplied, the client _may_ choose to not follow the link definition.
@@ -1800,23 +1790,41 @@ color: ["red", "green", "blue"]
The variables generated can be used in locations prescribed by the definition.
-### Variable substitution
+### <a name="variableSubstition"></a>Variable substitution
In all cases, _variables_ from request and responses may be substituted for link generation.
-The table below designates the source of the substitution value and the syntax for accessing it:
+The table below provides examples of variable expressions and examples of their use in a value:
-Source Location | reference identifier | example value | example reference | notes
----|:---|:---|:---|:---
+Source Location | variable expression | example reference | notes
+---|:---|:---|:---
HTTP Method | `$method` | `/users/{$method}` | The allowable values for the `$method` will be those for the HTTP operation
-Requested content type | `$accepts` | `/users/3?format={$accepts}` |
-Request parameter | `$request` | `/users/{$request.id}` | Request parameters must be declared in the `parameters` section for the operation or they cannot be used in substitution. This includes request headers
-Request body | `$requestBody` | `/users/{$requestBody.user.uuid}` | For operations which accept payloads, references may be made to portions of the `requestBody` or the entire body itself
+Requested content type | `$request.header.accept` | `/users/3?format={$request.header.accept}` |
+Request parameter | `$request.path.id` | `/users/{$request.path.id}` | Request parameters must be declared in the `parameters` section for the operation or they cannot be used in substitution. This includes request headers
+Request body | `$request.body` | `/users/{$request.body(/user/uuid)}` | For operations which accept payloads, references may be made to portions of the `requestBody` or the entire body itself
Request URL | `$url` | `/track?url={$url}` |
-Response value | `$response` | `{$response.uuid}` | Only the payload in the response can be accessed with the `$response` syntax
-Response header | `$responseHeader` | `{$responseHeader.Server}` | Single header values only are available.
+Response value | `$response.body` | `{$response.body(/uuid)}` | Only the payload in the response can be accessed with the `$response` syntax.
+Response header | `$response.header` | `{$response.header.Server}` |
From the request, the `parameter`s used in calling the operation are made available through the `$request` syntax.
For responses, the response payload may be used with the `$response` syntax.
-For both requests and responses, values will be substituted in the link in sections designated with the `$request` or `$response` keyword, surrounded by curly brackets `{}`.
+For both requests and responses, values will be substituted in the link in sections designated with a variable expression, surrounded by curly brackets `{}`.
+
+The variable expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax
+
+```
+ expression = ( "$url" | "$method" | "$request." [ source ] | "$response." [ source ])
+ source = ( header-reference | query-reference | path-reference | body-reference )
+ header-reference = "header." token
+ query-reference = "query." name
+ path-reference = "path." name
+ body-reference = "body(" fragment ")"
+ fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) with any instances of `(` or `)` escaped
+ name = *( char )
+ char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7)
+ token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)
+```
+
+The `name` identifier is case-sensitive, whereas `token` is not.
+
### Request parameter example
Computing a link from a request operation like such:
@@ -1848,10 +1856,10 @@ Can be used in a link like this:
```yaml
Addresses:
- href: '/users/{$request.id}/department'
+ href: '/users/{$request.path.id}/department'
```
-Where the `$request.id` is the value passed in the request to `/users/{id}`.
+Where the `$request.path.id` is the value passed in the request to `/users/{id}`.
For a `id` value of `10101110`, the generated link would be:
```yaml
@@ -1862,7 +1870,7 @@ href: '/users/10101110/department'
```yaml
Addresses:
- href: '/users/{$response.uuid}/address'
+ href: '/users/{$response.body(/uuid)}/address'
```
Where the `$response.uuid` from the example above would yield the target:
@@ -1876,7 +1884,7 @@ And the array example:
```yaml
ColorSelection:
- href: 'http://colors.my-server.com/colors/{$response.color}'
+ href: 'http://colors.my-server.com/colors/{$response.body(/color)}'
```
Would produce the following links:
@@ -2034,26 +2042,26 @@ components:
# returns array of '#/components/definitions/repository'
operationId: getRepositoriesByOwner
parameters:
- username: $response.username
+ username: $response.body(/username)
UserRepository:
# returns '#/components/definitions/repository'
operationId: getRepository
parameters:
- username: $response.owner.username
- slug: $response.slug
+ username: $response.body(/owner/username)
+ slug: $response.body.slug
RepositoryPullRequests:
# returns '#/components/definitions/pullrequest'
operationId: getPullRequestsByRepository
params:
- username: $response.owner.username
- slug: $response.slug
+ username: $response.body(/owner/username)
+ slug: $response.body(/slug)
PullRequestMerge:
# executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
operationId: mergePullRequest
parameters:
- username: $response.user.username # Should be $response.author.username?
- slug: $response.repository.slug
- pid: $response.id
+ username: $response.body(/user/username) # Should be $response.author.username?
+ slug: $response.body(/repository/slug)
+ pid: $response.body(/id)
definitions:
user:
type: object
@@ -2089,7 +2097,7 @@ components:
links:
UserRepositories:
# returns array of '#/components/definitions/repository'
- href: '/2.0/repositories/{$response.username}'
+ href: '/2.0/repositories/{$response.body(/username)}'
```
or an absolute `href`:
@@ -2099,7 +2107,7 @@ components:
links:
UserRepositories:
# returns array of '#/components/definitions/repository'
- href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.username}'
+ href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body(/username)}'
```
@@ -2131,7 +2139,7 @@ components:
UserCommitHistory:
operationId: userCommitHistory
parameters:
- username: $response.user.username
+ username: $response.body(/user/username)
page: 0
```

Updates to align links and callbacks