From 6e6c4f68faac7d85fd47dd54d6ac7a8097b9e3d8 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 17 Feb 2017 17:18:42 -0500 Subject: [PATCH 1/7] Callback review and preliminary message expression syntax --- versions/3.0.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index bbd5bac085..2587d03b76 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1555,15 +1555,70 @@ description: object created #### Callback 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 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -Callback name | [Callback Operation Object](#operationObject) | [Operation Object](#operationObject) | An operation object used to define a callback payload structure +Callback name | [Callback Operation Object](#operationObject) | [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 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: + +```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 +---|:--- +$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 +$response.header.Location | http://example.org/subscription/1 + ##### Callback Object Example @@ -1572,7 +1627,7 @@ A callback to the URL specified by the `url` parameter in the request ```yaml myWebhook: - '$request.url': + '$request.body.url': post: body: name: postResponse From 4197f43faf1eb674dc14d264d33a0a480aef22be Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 20 Feb 2017 15:47:59 -0500 Subject: [PATCH 2/7] Updates to align links and callbacks --- versions/3.0.md | 110 ++++++++++++++++++++++++++---------------------- 1 file changed, 59 insertions(+), 51 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 7cbc3f5d0d..93738797c7 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1561,38 +1561,26 @@ description: object created #### 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 ---|:---:|--- -Callback name | [Callback Operation Object](#operationObject) | [Operation Object](#operationObject) | An operation object used to define a callback request and expected responses +Callback name | [Callback Operation Object](#operationObject) | [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 #### 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 +### 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 ``` From 4068d0097778f9add9fe035f8c4ca0529fed996f Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 20 Feb 2017 22:06:43 -0500 Subject: [PATCH 3/7] Fixed property name of callbacks --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 93738797c7..8dc62da0d2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -589,7 +589,7 @@ Field Name | Type | Description parameters | [[Parameter Object](#parameterObject) | [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). requestBody | [[Request Body Object](#requestBodyObject) | [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. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. -callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation. +callbacks | [Callbacks Object](#callbacksObject) | The list of possible callbacks as they are returned from executing this operation. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. 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. 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. @@ -1559,7 +1559,7 @@ Response with no return value: description: object created ``` -#### Callback Object +#### Callbacks 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. From bc9da3180d3903cbfc96baa0e8c6fdae537696cf Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 21 Feb 2017 11:44:41 -0500 Subject: [PATCH 4/7] Fixed callback example --- versions/3.0.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 8dc62da0d2..18332e35dd 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1625,10 +1625,12 @@ A callback to the URL specified by the `url` parameter in the request myWebhook: '$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 From b268c06de2d3f7d4781151de61429e8759cedd8a Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 21 Feb 2017 17:20:49 -0500 Subject: [PATCH 5/7] Updates to Callback/Links based on meeting --- versions/3.0.md | 58 ++++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 18332e35dd..53d08edc5d 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1575,7 +1575,7 @@ This object can be extended with [Specification Extensions](#specificationExtens ##### 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)". +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). @@ -1611,8 +1611,8 @@ $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 @@ -1623,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: requestBody: description: Callback payload @@ -1735,11 +1735,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. 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/). +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). @@ -1749,7 +1749,7 @@ Because of the potential for name clashes, consider the `href` syntax as the pre #### Response Payload Values -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. +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. @@ -1801,10 +1801,10 @@ 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 | `$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 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.body` | `{$response.body(/uuid)}` | Only the payload in the response can be accessed with the `$response` syntax. -Response header | `$response.header` | `{$response.header.Server}` | +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. @@ -1818,8 +1818,8 @@ The variable expression is defined by the following [ABNF](https://tools.ietf.or 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 + 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) @@ -1872,7 +1872,7 @@ href: '/users/10101110/department' ```yaml Addresses: - href: '/users/{$response.body(/uuid)}/address' + href: '/users/{$response.body#/uuid}/address' ``` Where the `$response.uuid` from the example above would yield the target: @@ -1886,7 +1886,7 @@ And the array example: ```yaml ColorSelection: - href: 'http://colors.my-server.com/colors/{$response.body(/color)}' + href: 'http://colors.my-server.com/colors/{$response.body#/color}' ``` Would produce the following links: @@ -2044,26 +2044,26 @@ components: # returns array of '#/components/definitions/repository' operationId: getRepositoriesByOwner parameters: - username: $response.body(/username) + username: $response.body#/username UserRepository: # returns '#/components/definitions/repository' operationId: getRepository parameters: - username: $response.body(/owner/username) - slug: $response.body.slug + username: $response.body#/owner/username + slug: $response.body#/slug RepositoryPullRequests: # returns '#/components/definitions/pullrequest' operationId: getPullRequestsByRepository params: - username: $response.body(/owner/username) - slug: $response.body(/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.body(/user/username) # Should be $response.author.username? - slug: $response.body(/repository/slug) - pid: $response.body(/id) + username: $response.body#/user/username # Should be $response.author.username? + slug: $response.body#/repository/slug + pid: $response.body#/id definitions: user: type: object @@ -2099,7 +2099,7 @@ components: links: UserRepositories: # returns array of '#/components/definitions/repository' - href: '/2.0/repositories/{$response.body(/username)}' + href: '/2.0/repositories/{$response.body#/username}' ``` or an absolute `href`: @@ -2109,11 +2109,11 @@ components: links: UserRepositories: # returns array of '#/components/definitions/repository' - href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body(/username)}' + href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body#/username}' ``` -### Link Parameters +### 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. @@ -2141,7 +2141,7 @@ components: UserCommitHistory: operationId: userCommitHistory parameters: - username: $response.body(/user/username) + username: $response.body#/user/username page: 0 ``` From 17fdf10a0d1cb5b444cb9513e28bcba418ec7eca Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 21 Feb 2017 17:25:08 -0500 Subject: [PATCH 6/7] Almost missed Marsh's comment. --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 53d08edc5d..2b846e5a8e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1589,8 +1589,8 @@ Content-Type: application/json Content-Length: 123 { - "failedurl" : "http://clientdomain.com/failed" - "successurls : [ + "failedUrl" : "http://clientdomain.com/failed" + "successUrls : [ "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" @@ -1611,8 +1611,8 @@ $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#/failedUrl | http://clientdomain.com/stillrunning +$request.body#/successUrls/2 | http://clientdomain.com/medium $response.header.Location | http://example.org/subscription/1 From 9e6f58692600a09b88a6e9c0ac3568a9ef1bbe17 Mon Sep 17 00:00:00 2001 From: Darrel Date: Wed, 22 Feb 2017 13:25:43 -0500 Subject: [PATCH 7/7] Fixing spaces and capitals for Ron --- versions/3.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 2b846e5a8e..1a31113a46 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1562,13 +1562,13 @@ description: object created #### Callbacks 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. +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 ---|:---:|--- -Callback name | [Callback Operation Object](#operationObject) | [Operation Object](#operationObject) | An operation object used to define a callback request and expected responses +Callback name | [Callback Operation Object](#operationObject) | [Operation Object](#operationObject) | An Operation Object used to define a callback request and expected responses This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1577,7 +1577,7 @@ This object can be extended with [Specification Extensions](#specificationExtens 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). +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: