-
Notifications
You must be signed in to change notification settings - Fork 60
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Callbacks, Links and Webhooks pages #90
base: main
Are you sure you want to change the base?
Conversation
thanks @SensibleWood - going through this one. |
You the man @miqui |
specification/webhooks.md
Outdated
|
||
# Providing Webhooks | ||
|
||
Webhooks are a style of communication common in the API economy. Their purpose is to provide bi-directional communications from the API provider to the API consumer to support out-of-band events that do not fit into the pattern of REST APIs. Webhooks fulfill similar purposes to Callbacks in that they support transmitting information about asynchronous or long-running communications. The example of payments APIs discussed in the Callbacks topic also provides an example of the real-world implementations of Webhooks. Many payments API providers implement webhooks to communicate the result of payment operations as an alternative to callbacks. API consumers can implement a webhook at a URL of their choosing to receive out-of-band updates on a previously submitted, long-running request. This avoids implementing polling patterns, which many API providers find onerous to support. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we distinguish that with the callback that usually in the webhook the client is not the initiator of the request. like i can subscribe to the github webhook of commit , so that even if i do not do a commit but someone else i got notified
and that webhook suppose a pre registration
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added clarifications here and used the example of GitHub to show how pre-registration can facilitate using Webhooks.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A few comments, but this is coming together IMO.
|
||
# Providing Callbacks | ||
|
||
Callbacks are a feature of OAS that provides a relationship between a given [Operation](https://spec.openapis.org/oas/v3.1.0#operation-object) and a [Path Item](https://spec.openapis.org/oas/v3.1.0#path-item-object) that can be implemented by an API consumer. A callback allows an API provider to describe this relationship at design time, indicating that they can call an API consumer at a given URL based on the definition of both the Callback and dynamic values received during a given Operation. These are described as "out-of-band" by the specification as the expectation is the API provider can call such URLs independently of the Operation in which they are defined. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure this opening paragraph quite captures the purpose of callbacks. Maybe we can say something like "Callbacks are a way to describe HTTP requests sent from server to client as a followup to an earlier API call" or something? The point here is that the HTTP requests go the other way than they usually do - and for callbacks, they only do so as a followup to an earlier API call, unlike webhooks that have out-of-band registration and the requests can be sent in response to another trigger.
Co-authored-by: Lorna Jane Mitchell <[email protected]>
Co-authored-by: Lorna Jane Mitchell <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This example has moved to https://github.com/OAI/learn.openapis.org/blob/main/examples/v3.1/tictactoe.yaml
Summary of changes:
webhooks
property.👍