From eefdc6988a457cdf3bc611955862c8f4f7cefe80 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 15 Jan 2020 20:52:10 +0000 Subject: [PATCH 1/7] Add webhooks as a top-level element to the spec --- versions/3.1.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 09f994cf14..5ab776ce6d 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -197,6 +197,7 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. +webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that may be received as part of this API. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. This object MAY be extended with [Specification Extensions](#specificationExtensions). From ca5a8af323c6fb17139aba8e7620f39c42120508 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 14 Jan 2020 11:55:24 +0000 Subject: [PATCH 2/7] Add the changes from #2048 and signpost webhooks --- versions/3.1.0.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 5ab776ce6d..1008282b39 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1845,6 +1845,8 @@ A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests 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. +To describe incoming requests from the API provider independent from another API call, use the [`webhooks`](#oasWebhooks) field. + ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- @@ -1894,25 +1896,41 @@ $request.body#/successUrls/2 | https://clientdomain.com/medium $response.header.Location | https://example.org/subscription/1 -##### Callback Object Example +##### Callback Object Examples -The following example shows a callback to the URL specified by the `id` and `email` property in the request body. +The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. ```yaml -myWebhook: - 'https://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': +myCallback: + '{$request.query.queryUrl}': post: requestBody: description: Callback payload - content: + content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': - description: webhook successfully processed and no retries will be performed + description: callback successfully processed ``` +The following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body. + +```yaml +transactionCallback: + 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': + post: + requestBody: + description: Callback payload + content: + 'application/json': + schema: + $ref: '#/components/schemas/SomePayload' + responses: + '200': + description: callback successfully processed +``` #### Example Object From 7ba4b08d917928fab1a2158f00efa8afaa5c1f7d Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 14 Jan 2020 12:26:56 +0000 Subject: [PATCH 3/7] Add an example of webhooks --- examples/v3.1/webhook-example.yaml | 61 ++++++++++++++++++++++++++++++ versions/3.1.0.md | 3 +- 2 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 examples/v3.1/webhook-example.yaml diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml new file mode 100644 index 0000000000..6dff7ce018 --- /dev/null +++ b/examples/v3.1/webhook-example.yaml @@ -0,0 +1,61 @@ +openapi: 3.1.0 +info: + title: Webhook Example + version: 1.0.0 +paths: + # OpenAPI specs all need a paths element + /pets: + get: + summary: List all pets + operationId: listPets + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + required: false + schema: + type: integer + format: int32 + responses: + '200': + description: A paged array of pets + content: + application/json: + schema: + $ref: "#/components/schemas/Pets" + +webhooks: + # Each webhook needs a name + newPet: + # This is a Path Item Object, the only difference is that the request is initiated by the API provider + post: + requestBody: + description: Information about a new pet in the system + content: + application/json: + schema: + $ref: "#/components/schemas/Pet" + responses: + 200: + description: Return a 200 status to indicate that the data was received successfully + +components: + schemas: + Pet: + required: + - id + - name + properties: + id: + type: integer + format: int64 + name: + type: string + tag: + type: string + Pets: + type: array + items: + $ref: "#/components/schemas/Pet" + + diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 1008282b39..972495b108 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -197,7 +197,8 @@ Field Name | Type | Description security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. -webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that may be received as part of this API. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. +webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that may be received as part of this API. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. + This object MAY be extended with [Specification Extensions](#specificationExtensions). From 98e8617cade12bc452cafbe1e209805caf49806c Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 15 Jan 2020 21:03:03 +0000 Subject: [PATCH 4/7] Relocate and expand on webhooks section following feedback --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 972495b108..729e621067 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -193,11 +193,11 @@ Field Name | Type | Description info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. +webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer is expected to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. -webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that may be received as part of this API. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. This object MAY be extended with [Specification Extensions](#specificationExtensions). From b3ed2d4ed8b58873410fc0d99498a7c7995681be Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 16 Jan 2020 17:11:16 +0000 Subject: [PATCH 5/7] Better wording to describe expectations on API consumers --- examples/v3.1/webhook-example.yaml | 2 +- versions/3.1.0.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml index 6dff7ce018..c7ace989e8 100644 --- a/examples/v3.1/webhook-example.yaml +++ b/examples/v3.1/webhook-example.yaml @@ -36,7 +36,7 @@ webhooks: schema: $ref: "#/components/schemas/Pet" responses: - 200: + "200": description: Return a 200 status to indicate that the data was received successfully components: diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 729e621067..65d71d6994 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -193,7 +193,7 @@ Field Name | Type | Description info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. -webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer is expected to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. +webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. From db714c47bee676d43843b5063e9d4792dc37d7fb Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 16 Jan 2020 17:18:30 +0000 Subject: [PATCH 6/7] Clearer wording for why the paths element is here --- examples/v3.1/webhook-example.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml index c7ace989e8..664966a35a 100644 --- a/examples/v3.1/webhook-example.yaml +++ b/examples/v3.1/webhook-example.yaml @@ -3,7 +3,7 @@ info: title: Webhook Example version: 1.0.0 paths: - # OpenAPI specs all need a paths element + # OpenAPI documents all need a paths element /pets: get: summary: List all pets From 3fb1bffff5ef599418420e7d27593418deeaa2a3 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 16 Jan 2020 17:30:59 +0000 Subject: [PATCH 7/7] Update language to make callbacks clearer --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 65d71d6994..24867aba02 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1899,7 +1899,7 @@ $response.header.Location | https://example.org/subscription/1 ##### Callback Object Examples -The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. +The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a callback that goes with the subscription operation to enable registering for the callback. ```yaml myCallback: