Add Callbacks, Links and Webhooks pages #90
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.
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.
I've added clarifications here and used the example of GitHub to show how pre-registration can facilitate using Webhooks.
|
|
||
| # 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.
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.
There was a problem hiding this comment.
i would agree that
i would rather start with this parapgraph
callbacks are defined as asynchronous, out-of-band requests that your service sends to another service in response to certain events.
i would insists on the difference with webhook, that a callback is a reaction toward a first incoming call. That is the main differentiator, Webhook requires registration (that can be static or dynamic)
there is no sponateous callback versus there can be for webhook
Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>
Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>
There was a problem hiding this comment.
This example has moved to https://github.com/OAI/learn.openapis.org/blob/main/examples/v3.1/tictactoe.yaml
|
@SensibleWood I still think this would be really valuable if we could add it. Could you update the branch and let's try to publish? (or let me know and I can pick this up) |
|
@lornajane sorry this dropped off my list of things to do. I'll try and get it done before Xmas as the goose is currently too fat for me to fit it in immediately |
|
|
||
| # 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 or Callbacks. 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. 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.
Their purpose is to provide bi-directional communications
this sentense may be missleadding, as webhook is not bi directionnal ,
and it is not clear the differences between webhook and callback
my own definition of webhook vs callback is given a server S , and a Client C1
given an action done by C1, callback is a called from S to C1 ,
vs webhook supports more a brodcast pattern , meaning that given 2 clients C1, C2 an action done by C2 can trigger a webhook that C1 will receive . meaning the receiver of the call is not a reaction toward a previous call
it could even be a webhook due to date . this is why it requires a registration mecanism , like a clock for instance
callback does not need it , url can even be provided at run time
Summary of changes:
webhooksproperty.👍