OAS:OpenAPI Editor/Callbacks

From Remain Software

Callbacks

In OpenAPI 3 specs, you can define callbacks – asynchronous, out-of-band requests that your service will send to some other service in response to certain events. This helps you improve the workflow your API offers to clients. A typical example of a callback is subscription functionality – users subscribe to certain events of your service and receive a notification when this or that event occurs. For example, an e-shop can send a notification to the manager on each purchase. These notifications will be “out-of-band”, that is, they will go through a connection other than the connection through which a visitor works, and they will be asynchronous, as they will be out of the regular request-response flow. In OpenAPI 3, you can define the format of the “subscription” operation as well as the format of callback messages and expected responses to these messages. This description will simplify communication between different servers and will help you standardize the use of webhooks in your API.

Add Callback

To add a callback, select the Paths tab at the bottom. Then select the operation you want to add a callback to. On the right editor, select the Callbacks tab then from there click the 'Add new callback' link.


Oas3 add callback.png


Add Callback Path

In the previous step, only the name of the callback has been added.

To add a callback path, click the link 'Add callback path' from the local toolbar. A path input field is shown where you can fill in the callback path input.


Oas3 add callback path.png

Delete Callback

To delete a callback, click the Delete link button from the local toolbar.


Oas3 delete callback.png

Add Callback Content and Response

Below the callback path, we specify the method of the callback message and define the message format and the expected responses. These definitions are similar to regular request and response definitions.

To add the callback method, right mouse click on the callback path, then select New Operation.


Oas3 callback method.png


Add Callback Method Request Body

To add the request body of the callback method, select the method, then select the Request Bodies tab.


Oas3 callback method request body.png


Add Callback Method Response

To add a response to some callback method, select the method, then select the responses tab.


Oas3 callback method response.png