OpenAPI v3 Callbacks

[pvcarrera]

As you can see in the OAS3 docs: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callback-object-example callbacks are now part of the specification.

It would be nice if prims could load the callback objects from the document and trigger the corresponding callback requests.

Here you have some ideas:

Given the callback-example document from the specification, if we run:

prism mock callback-example.yaml --callback_delay=30000

The CLI output could be something like:

…  awaiting  Starting Prism…
★  star      Dynamic example generation enabled.
✔  success   Prism is listening on http://127.0.0.1:4010
●  note          POST       http://127.0.0.1:4010/streams
●  onData      POST       {$request.query.callbackUrl}/data  delay 30s.

This means that after the 30s. of delay a request with sample data based on the requestBody defined inside the callbacks/onData will be triggered to the {$request.query.callbackUrl}/data URL.

In case no delay is provided the callback request will be trigger immediately.

The CLI could also log when the request is made to the callback URL:

…  awaiting  Starting Prism…
★  star      Dynamic example generation enabled.
✔  success   Prism is listening on http://127.0.0.1:4010
●  note          POST       http://127.0.0.1:4010/streams

30s. after a request POST http://127.0.0.1:4010/streams?callbackURL=http://callback.com

●  callback request          POST       http://callback.com/data

The OAS3 example adds the callbackURL as a query param but I guess it can be also send as a body param.

[philsturgeon]

Another source of inspiration for this feature is the Stripe CLI, specifically the listen command: https://github.com/stripe/stripe-cli#listen

[philsturgeon]

This issue is being worked on for callbacks in a cool way, @StefanDywersant has started some code where basically when you make a HTTP request to prism, if it is going to send callbacks it will fire HTTP requests at the callback URL defined in the users description document. Awesome! This covers "Callbacks" well.

1. I noticed that examples of callbacks are a bit confusing in 3.0.x so I updated them: Improved callback examples OAI/OpenAPI-Specification#2048

2. OpenAPI has a separate concept called Webhooks, which was added as proposal in 3.0.x. This is a little different, as it talks about events which might not be sent as a follow-up to a specific HTTP request (like Slack and Stripe, where you subscribe through a UI and give them a URL to hit, then you just get stuff thrown at you randomly).

We will not be able to cover webhooks in this way, but some of the same code could be used internally. Maybe take a look at webhooks and try to keep that in mind when building this solution.

So, @StefanDywersant, we might need to split this in two. We can keep this issue for callbacks, but this issue and your PR will need to avoid using the word "webhook" as that will clash with the proposal. I'll make a new issue for webhooks, which will need to be initiated by the user via a CLI interface as we were suggesting above with the stripe-cli example.

Does this sound good?

[karol-maciaszek]

@philsturgeon completely. I wasn't aware that there is upcoming webhooks: keyword in OpenApi spec. I changed PR name to Callbacks. All the code uses callback internally already.