Asynchronous Operations

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.
How do we return the operation ID?
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 Created status code.
In the header of the response, we will leave the location of the operation object in the Location header, like this:
// response header
Location: /v1/operations/dc3a7730-53e2-4af6-acc9-d13b2fcf10e2
How do you use the operation ID?
The operations API consists of one endpoint - the GET operation endpoint - which returns the status of a given operation.
Resource
Field
Type
Description
status
string
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.
txHash
string
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
string?
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.
​

Field	Type	Description
status	string	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.
txHash	string	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	string?	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.

Last modified 4mo ago