Long-running operations

Some work cannot finish inside a request: provisioning a site builds a database, buckets, routing and seeded content; a search reindex walks everything the site has. Rather than answer 202 and leave you guessing, those calls name an Operation — a resource you can poll, and the only honest answer to "is it done yet".

Code
state='{"done": false}'
until [ "$(jq -r '.done' <<<"$state")" = true ]; do
  sleep 2
  state=$(curl_json "$SITE_API/site-api/v1/operations/$signup_token")
  jq -r '"  " + (.metadata.step // "?")' <<<"$state" >&2
done

# Done means finished, not succeeded: exactly one of `response` and `error` is there.
jq -e '.error | not' <<<"$state" >/dev/null || { jq '.error' <<<"$state" >&2; exit 1; }
SITE_URL=$(jq -r '.response.website_url' <<<"$state")

Three habits make polling one of these correct:

• done means finished, not succeeded. Exactly one of response and error is present once it flips, and the error is the ordinary Status shape.
• Read metadata.step, not a percentage. The step is the named hop the work is on; where nothing counts anything, no number is reported rather than a made-up one.
• Cancelling is a request, not an event. :cancel records it and returns the operation still running; the work stops at its next checkpoint, if it has one left, and you learn the outcome from done — a CANCELLED error means it stopped, success means it finished anyway.

17. Long-running operations (AIP-151)

Anything that returns before the work is done MUST return an Operation, not a bare 202 and a hope.

Code
{
  "name": "websites/6a5e.../operations/64ff...",
  "done": false,
  "metadata": { "type": "PROVISION_WEBSITE", "step": "SEEDING_CONTENT", "progress_percent": 40 }
}

When done is true, exactly one of response (the resulting resource) or error (a Status body, §13) is present.

• GET {operation_name} polls. POST {operation_name}:cancel requests cancellation; the operation is not cancelled until done is true with a CANCELLED error.
• The initiating call returns 202 Accepted with the Operation and a Location header pointing at it.
• Operations are retained at least 24 h after completion.

An Operation is server-minted. It has Get and :cancel and nothing else: a client cannot create one, and a List of every operation a resource has ever run is an audit log, which is a different resource. It carries no etag either — §14 wants one where there are concurrent editors, and this resource has no editors: :cancel raises a flag, it does not submit a version.

Cancellation is a request, honoured at a checkpoint. :cancel records it and returns the operation, still running. A worker consults the flag where it can still stop; past its last checkpoint the work finishes and the operation reports success — which the done/CANCELLED rule above makes visible rather than letting the caller assume the cancel took. :cancel on an already finished operation is FAILED_PRECONDITION: finished work cannot be un-finished.

metadata is service-specific and honest. Emit step — the named hop the work is on — rather than a progress_percent nothing measures. progress_percent belongs in the example above and in a service that genuinely counts something.

A kick-off that also creates an addressable resource keeps its 201. §17 covers calls whose whole result is asynchronous. Where the resource exists by the time the response is written — a website whose provisioning_status is PENDING, a user whose site is still being built — the answer stays 201 + Location + the resource, plus an operation field naming what to poll. Downgrading that to 202 would take the resource's name away from the caller and hand back only a receipt for work.

And there is no operation field when the resource is what you poll. A resource created to be one run of work — ai_executions is the platform's one — already carries the whole lifecycle an Operation would: a state that ends, an error when it ends badly, a :cancel that raises the same flag honoured at the same kind of checkpoint, and, unlike an Operation, a List that is its history. Minting an Operation beside it would publish two names for one run and two places to read whether it finished.