We consider some API endpoints to be "asynchronous", which means the initial call doesn’t return the results of the operation. We provide this capability for endpoints that require a blockchain network call, because sometimes a blockchain call can take much longer than expected due to network congestion or other reasons.
In these cases, if we offered a synchronous endpoint, the request may have to remain open and blocking for much longer than normal, or it may just time out. To prevent this from happening, we submit the transaction to the blockchain and immediately return to you the operation ID, which you can use to poll against our operations API endpoint to get the results. This is largely inspired by Azure’s Asynchronous Request-Reply pattern.
Once we successfully receive your request for an async operation (such as creating a new Kudos token), we will return the call with a
202 Createdstatus code.
In the header of the response, we will leave the location of the operation object in the
Locationheader, like this:
// response header
The operations API consists of one endpoint - the GET operation endpoint - which returns the status of a given operation.
Status of the operation. Options are pending, processing, success, and error. The terminal states are success and error. Anything else and you should hit the endpoint again at a later time.
The transaction hash of the blockchain operation that’s been processed by the underlying blockchain network. You can use this to query the status directly with the blockchain as needed. Note that we may do additional operations within our server after we confirm that the blockchain transaction has been mined.
ResourceID returned after the blockchain operation is completed. It may be null for cases where the operation creates the new resource (ex: a new Kudos token). In such cases, upon success of the operation, it will return the ID of the newly created resource.