APIs send data when requested, but callbacks can send data when an event is triggered to the callback url. So the client doesn't need to check repeatedly, if new data is available.
A Callback API is defined by the service calling the API. (Also referred to as a Webhook or Reverse API)
e.g. When a Callback API is called, the responder must handle the request and provide a response that conforms to what the caller expects.
Here is an example of a callback API with callback url.
The callback URL will be invoked by the API method you're calling after it's done.
The callback URL can be set in the server configuration, database or passed as a parameter in the ruquest as above example.
|client requests the API url to get data
|callbacks call the client url to send
|API Clients dont need a running server. They can request data when they want
|Callback callback need active servers. They have to be active all the time accept connections.
|APIs cannot push data to other systems
|callbacks can push data to a given url
|On API Request
|On Event Trigger
|Comes into the server
|Goes out to callback URL
|Pushed to callback url
callbacks are similar to APIs with respect to providing data to the clients. They can be built within the same API server. The user needs to provide a callback url, where they need the data send.
Setting up Callback reciever
Registering the Callback url is a one time configuration activity that API user performs. The callback url from every user is different. So the API server can send data when available to different clients.
Steps to create Callback with API
The application recieving the callback gets information in the form of a request. A server can send data in GET or POST parameters in the callback request.
GET Request Example
POST Request Example
Both the above api callback examples send data in the form of request.
In the above example, the application recieving the callback should respond back with an acknowledgement to the server issuing the callback, that it recieved the callback successfully. This completes the api callback cycle, and both parties exchange information. Along with acknowledgement, the callback api can send data in the response.
GET Request Example
The above APIs are HTTP GET and POST rest api callbacks. They can use rest api status codes like 400, 422 to indicate invalid callback requests.
If the application is unable to process the callback request, it should return 500 Internal error. This is possible when too many callback requests are sent in a short interval and the application handling the request crashes.
For recieving multiple callbacks on a single identifer or reference number, request identifer in the rest api callback url can be used as follows.