LasneF
commented
8 months ago to me formalizing the client subscription model is outside of the scope of OAS, as it is touching the architecture of the software
for instance in some case you subscribe during the application creation (as same time you create client id/secret) you subscribe to the event you want to get .
in other implementation you subscribe at run time
also you might want to subscribe to a particular semantic of an event , for instance subscribing only to pet jumping and not running , so the subscription itself can have semantics
What you may use is the Link object ( https://spec.openapis.org/oas/latest.html#link-object )
Webhooks were added in addition to callbacks in OAS 3.1 with this proposal: https://github.com/OAI/OpenAPI-Specification/pull/1974
I understand callbacks to be typically delayed responses to a request - hence one provides a dedicated callback URL in order to identify the matching request a delayed response belongs to.
Webhooks are different in that unrelated events/messages are sent to the client. Great to see that this was added in OAS 3.1.
I was wondering whether an option could be added to formalize a client subscribing to events as well as unsubscribing from them. There likely will be an API to do so, but it won't be possible for a OAS tool chains to figure out what APIs to call to subscribe/unsubscribe to events and what parameters to use to identify a subscription. This could be as simple as the client's webhook URL, but there are implementations that use a different subscription identifier.
For the "newPet" webhook example, it would be good to have a reference to a path elements that performs the subscription on the server or the path elements a decorator identifying which webhook and whether it's a subscribe/unsubscribe.