Add Callbacks, Links and Webhooks pages #90
Conversation
|
thanks @SensibleWood - going through this one. |
You the man @miqui |
|
|
||
| ```yaml | ||
| callbacks: | ||
| statusCallback: |
There was a problem hiding this comment.
your documentation is great as it is confusing me ...
i would not expect that i got a callback like this
to me i understood the callback pattern mode like this
if C is the client and S the server
C call S on POST /long-running-Task
but in your scenario with location it look that the task return a location
it looks like C need to call for the status of the long running task
in fact this would be just a dynamic resource creation that for
vs i thought that it was more that C call S POST /long-running-task
and that the S call then back the client with this is Finished , or that the sever call in progress , then server call again Finished
is the statement "API consumer should call a callback URL" correct ? i was expecting more the serveur to call the callback URL that the Client must implement
There was a problem hiding this comment.
Yes you are right. I'll refactor
There was a problem hiding this comment.
@LasneF I've now refactored the page with the correct facts. Basically I've never used Callbacks in anger and essentially didn't read the specification correctly. Thanks for calling this out.
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.
Summary of changes:
webhooksproperty.馃憤