Long-running API operations: the 202 answer, the action_id and following the result

The short answer: operations that take time answer straight away with a 202 and an action_id, because the work carries on after the answer. Do not repeat the request: follow the result with GET /v1/actions/{id} until the status is done or failed.

Which operations answer 202

Operation	What takes time
Registering, renewing and transferring domains	The work carries on after the answer. Some extensions, including .mz, are handled manually and take longer.
Starting, stopping and restarting a VPS	The action is queued. Starting usually takes about 2 minutes, and stopping about 6.
Buying an extra	The action ends with the payment; delivery is followed separately.

The states of an action

Status	What it means
queued	Queued, waiting to start.
running	Running.
done	Finished successfully.
failed	Failed. The reason is in result.

curl https://api.mozout.com/v1/actions/0f8fad5b-d9cb-469f-a165-70867728950e \
-H "Authorization: Bearer $RLX_API_KEY"

The answer gives the id, the type, the target (the domain, for example), the status, the result and when it was created and last updated. You only see your own account's actions.

Following an action without wasting requests

1	Store the action_id as soon as the 202 arrives, next to the operation that produced it.

2	Check at a calm pace. One request every few seconds is enough; very fast loops only burn through the request limits.

3	Stop when the status is done or failed, and read the result.

4	Confirm the final effect with an ordinary read: the domain in GET /v1/domains/{domain}, the server in GET /v1/servers/{id}, the extra in GET /v1/extras/{id} with the extra_id from the answer.

Repeating the request instead of following it speeds nothing up, and on a server it returns 409 action_in_progress, because each server runs one action at a time (the running action_id is in details). For purchases, always use the Idempotency-Key, so a retry never buys twice.

Server specifics

Case	What happens
Who can check it	Only the key that requested the action.
How fresh the status is	It comes from a copy up to 20 seconds old and counts towards the account read limit. Past that limit, the action stays running until the next read.
No confirmation in time	failed with timed_out in result.reason. Check the server's state in that case.
The server is no longer available	failed with server_gone.

Why does the answer not carry the result right away? Because some tasks depend on other systems and take minutes. It is the difference between a synchronous and an asynchronous answer, explained in synchronous or asynchronous.

Want to watch an action run without risk? Make the request with a Sandbox key and follow it in the documentation, reached from the API page.

See the API page

Categories

Categories