Merge pull request OAI#891 from OAI/dm/callback-review

Callback review and preliminary message expression syntax

Author: darrelmiller

versions/3.0.md

@@ -589,7 +589,7 @@ Field Name | Type | Description
 <a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).
 <a name="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation.  The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague, `requestBody` shall be ignored by consumers.
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
-<a name="operationCallbacks"></a>callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation.
+<a name="operationCallbacks"></a>callbacks | [Callbacks Object](#callbacksObject) | The list of possible callbacks as they are returned from executing this operation.
 <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
 <a name="operationSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
 <a name="operationItemServer"></a>servers | [Server Object](#serverObject) | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
@@ -1493,17 +1493,62 @@ Response with no return value:
 description: object created
 ```
 
-#### <a name="callbackObject"></a>Callback Object
+#### <a name="callbacksObject"></a>Callbacks Object
 
-A container for possible out-of band callbacks from an operation. A callback may be returned from an operation, calling back to the path specified in the operation 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 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 payload structure
+<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 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 JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901). 
+
+
+For example, given the following HTTP request:
+
+```http
+POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
+Host: example.org
+Content-Type: application/json
+Content-Length: 123
+
+{
+  "failedUrl" : "http://clientdomain.com/failed"
+  "successUrls : [
+    "http://clientdomain.com/fast",
+    "http://clientdomain.com/medium",
+    "http://clientdomain.com/slow"
+  ] 
+}
+
+201 Created
+Location: http://example.org/subscription/1
+
+```
+
+Here are the examples of how the various expressions evaluate, assuming a the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`.
+
+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#/failedUrl | http://clientdomain.com/stillrunning
+$request.body#/successUrls/2 | http://clientdomain.com/medium
+$response.header.Location | http://example.org/subscription/1
+
 
 ##### Callback Object Example
 
@@ -1512,12 +1557,14 @@ A callback to the URL specified by the `url` parameter in the request
 
 ```yaml
 myWebhook:
-  '$request.url':
+  '$request.body#/url':
     post:
-      body:
-        name: postResponse
-        schema:
-          $ref: '#/definitions/SomePayload'
+      requestBody:
+        description: Callback payload
+        content: 
+          'application/json'
+            schema:
+              $ref: '#/components/definitions/SomePayload'
       responses:
         200:
           description: webhook successfully processed an no retries will be performed
@@ -1631,11 +1678,11 @@ The `Link Object` is responsible for defining a possible operation based on a si
 
 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.
-description | string | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
+href        | `string`    | 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](#linkParameters) | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
+headers     | [Headers Object](#headersObject)    | 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). 
 
@@ -1645,7 +1692,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 be referenced using a JSON Pointer fragment Id.
 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. 
 
@@ -1688,23 +1735,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}`        | Single header values only are available
 
 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)  
+      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:
@@ -1736,10 +1801,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
@@ -1750,7 +1815,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:
@@ -1764,7 +1829,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:
@@ -1922,26 +1987,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
@@ -1977,7 +2042,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`:
@@ -1987,11 +2052,11 @@ 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}'
 ```
 
 
-### Link Parameters
+### <a name="linkParameters"></a>Link Parameters
 Using the `operationId` to reference an operation in the definition has many benefits, including the ability to define media-type options, security requirements, response and error payloads.
 Many operations require parameters to be passed, and these may be dynamic depending on the response itself.
 
@@ -2019,7 +2084,7 @@ components:
     UserCommitHistory:
       operationId: userCommitHistory
       parameters:
-        username: $response.user.username
+        username: $response.body#/user/username
         page: 0
 ```