Asynchronous APIs

overview asynchronous apis enable the client to send a request and continue with other tasks without waiting for an immediate response the server processes the request in the background and responds upon completion this approach offers several benefits, including higher scalability, efficient resource usage, and non blocking operations os1 simplifies implementation complexity by providing clients with the option to consume api callbacks through configurable webhooks lossless server side events propagation of server side events to multiple clients orchestrator for distributed processing of events architecture tip designing applications with async apis is different from designing with sync apis in rare cases the api might fail asynchronously! use custom validation plugins to rule out any possibility of delayed/lazy failure use appropriate ui design for listing to reflect the difference between tentatively added/modified data objects from definitively added/modified data objects additionally you can also setup callbacks for your asynchronous requests, setting up callback notifications follow the steps below to receive asynchronous updates step 1 register the callback url define a unique callback url in your application that will receive the updates then, ensure the url is publicly available and can handle incoming http requests step 2 specify the callback url in the request to listen to updates, send an api request to os1 specifying your callback url where we'll send the requested information see the sample request below for creating a container curl request post \\ \ url https //{base url}/core/api/v2/containers/containerid \\ \ header 'accept application/json' \\ \ header 'content type application/json' \\ \ data ' { "callback" { "url" "https //os1 sample requestcatcher com/" }, "ishazmat" false, "iscontainerizable" true, "isreusable" false } step 3 handling callbacks once we receive and process the api request, our system sends an update about the requested information to the defined callback url with the following information event type the type of event that triggered the update service the event’s service type (participant, container, or entity) data the data associated with the event lastly, configure your app to handle callbacks using the following parse the incoming request your app should parse the incoming post request to extract the event information when receiving a callback see the example below of the response payload sent to the callback url for the container creation mentioned above { "data" { "id" "string" }, "request" { "uri" "string", "method" "post", "querystring" "string", "body" {} } } process the update based on the type of event and service, your app should perform the appropriate action, such as displaying a notification or triggering a specific workflow send an acknowledgment once your app processes the update, your app should send one of the following http responses acknowledging that the callback was accepted 200 202 signature verification in callbacks the callback feature is used in different services of os1 signature verification is implied in the callback system to prevent unexpected and unauthenticated loads on that service whenever a callback is received it can be verified at os1 it provides the ability to register a token/secret return an hmac signature with every callback