Skip to content
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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

SensibleWood
Copy link
Collaborator

This work is connected to #76

Summary of changes:

  • Added page, diagram and example for Callback object.
  • Added page, diagram and example for Link object (not in scope of referenced ticket, but hey-ho).
  • Added page, diagram and example for webhooks property.
  • Corrected the security examples I got wrong when I wrote the security page (slap on the wrist!)
  • Some typos/syntax things I saw whilst doing this.

👍

@miqui
Copy link
Collaborator

miqui commented Mar 25, 2024

thanks @SensibleWood - going through this one.

@SensibleWood
Copy link
Collaborator Author

thanks @SensibleWood - going through this one.

You the man @miqui

specification/callbacks.md Show resolved Hide resolved

# 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.
Copy link
Member

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

Copy link
Collaborator Author

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.

Copy link
Collaborator

@lornajane lornajane left a 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.

specification/security.md Outdated Show resolved Hide resolved
specification/webhooks.md Outdated Show resolved Hide resolved

# 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.
Copy link
Collaborator

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.

@lornajane lornajane requested a review from LasneF June 11, 2024 08:15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants