Skip to content

Docsio v2 is out

See changelog
← Docsio Research

API documentation · Research synthesis

Async API docs should explain what happens after 202

What async API docs should explain after HTTP 202: progress, polling, cancellation, expiry and service-defined evidence of completion.

By Docsio Research13 min read

An accepted request is the start of a workflow, not proof that the job finished. We connect HTTP semantics with Google and Microsoft guidance to show how documentation can carry readers from acceptance to a verified outcome, including cancellation, lost responses and expired operation records.

Key findings

  • HTTP 202 indicates acceptance for processing, without promising eventual completion. The remaining workflow needs its own documented contract. RFC 9110

  • Delete can mean different things: Microsoft’s architecture pattern uses it to request cancellation, while Google’s operation deletion explicitly does not cancel work. Readers need the endpoint’s meaning, not an assumption based on the verb. Microsoft pattern Google operations

  • The ability to start work does not always include permission to observe it. Azure Resource Manager documents that distinction for operation tracking. ARM tracking

  • Our proposed review unit is the complete operation journey: an identifiable task, interpretable state, supported next action and verifiable result. This is a documentation method, not an executed reliability benchmark.

How we researched this

Research synthesis checked on November 20, 2026. We independently inspected eight original standards, interface definitions, API proposals and official provider-documentation pages. These establish intended semantics and recommendations, not measured implementation reliability. Sonar Pro and Sonar Deep Research assisted discovery and challenge; their summaries were not accepted as verification. We selected sources for lifecycle differences, not a representative sample of APIs. The matrices and review exercises below are our proposed editorial method. We made no provider API calls, measured no task completion rates and tested no customer integrations.

What does an accepted request actually prove?

A quickstart that ends at an accepted response can leave its most important instruction unwritten: how the reader knows the requested work happened. For an export, that may mean obtaining a usable file. For an import, it may mean understanding which records were applied. For provisioning, it may mean confirming that the new resource is usable.

RFC 9110, published in June 2022, separates acceptance from completed processing. It also says the request might not ultimately be acted upon. Its guidance points toward a status monitor, but does not prescribe one operation schema, cancellation endpoint or polling algorithm. HTTP 202 semantics

Our recommendation is to write the user’s end condition before documenting the initial request. “The server returned 202” is a transport observation. “The requested export is ready and the caller can retrieve it” is an outcome. The guide should explain the evidence that connects them.

For a documentation review, separate these questions:

LayerQuestion the reader needs answeredEvidence to specify
SubmissionWas the request accepted or rejected?Initial response and its exact meaning
OperationWhich task is being tracked?Durable identifier and supported lookup route
ProgressIs there more work to wait for?Documented nonterminal states and observation rules
OutcomeDid this task succeed, fail or stop?Terminal state and result or error representation
UseCan the intended result be used?Retrieval, access and any product-specific readiness check

This table is a proposed writing outline, not a standard all APIs must implement. A service may combine several layers in one response. The editorial task is to make those relationships explicit, rather than force a particular architecture onto an existing API.

Start the guide with a short account of the journey. Then keep the detailed field definitions in the reference and link to them at the decision point. Someone following the task should not have to infer a state machine from five disconnected endpoint pages. Our earlier workflow coverage report explains that broader division between references and task guides.

Which lifecycle rules belong to the provider?

Microsoft’s architecture pattern describes a successful status read returning HTTP 200 while work remains pending, with a possible 303 redirect when a result is ready. That is an implementation pattern, not the meaning of every successful HTTP response. Asynchronous request-reply pattern

Google’s operation definition uses a different representation: when done is false, neither error nor response is set; when done is true, one of those result fields is available. A reader must interpret completion and outcome separately. Google operation definition

Azure Resource Manager adds another distinction. Its tracking guidance instructs clients to use the Azure-AsyncOperation header when present and Location as a fallback. It also says resource-group-level permission can be necessary to track an operation even when resource-level permission allowed the caller to start it. ARM operation tracking

These differences are enough to reject a universal recipe such as “poll Location until HTTP 200, then declare success.” The right rule comes from the endpoint and API version being documented.

Use a small contract worksheet before writing sample code:

Contract itemRecord for this endpointAvoid assuming
Tracking handleExact field or header and its scopeEvery operation uses Location
State interpretationTerminal and nonterminal valuesHTTP success means job success
AuthorizationPermissions for start, observe and retrieveThe same permission covers all three
ResultInline result, resource address or another stepA completion flag contains the deliverable
Unknown valuesSupported fallback and escalationAn unfamiliar state is terminal

The worksheet is our proposal. Its value is in forcing an owner to resolve ambiguity before it becomes runnable guidance. If the implementation has no supported recovery path, record that limitation rather than invent an endpoint to make the article read smoothly.

Keep raw HTTP and SDK examples distinct. An SDK may hide the polling loop or wrap a terminal failure in an exception. The guide should name the SDK and version it describes, explain what the helper returns, and show how to retain enough information to resume or investigate. A method name such as wait or result is not sufficient evidence of its exact behavior.

For access troubleshooting, test the whole journey under the role recommended to customers. Testing only the create request with an administrator account cannot demonstrate that the documented role can inspect progress or retrieve the output.

How should a reader wait, leave and return?

Google’s Service Infrastructure polling guide recommends a 10-second backoff when repeatedly calling operations.get. This is a recommendation for the APIs covered by that guide, not a general performance target or a universal interval. Google polling guide

An interval tells a client when to ask again. It does not tell the reader how long the overall job will take, whether an unchanged status is abnormal, or what happens when the local process exits. Our proposed documentation review treats those as separate decisions.

A useful waiting example should make its stopping rule visible. Explain which terminal states end observation, what a client-side deadline means, and how to continue observing later. If the application stops waiting, the guide should avoid claiming the server stopped processing unless that is part of the actual contract.

For a resumable workflow, identify the information the caller should retain. That might include an operation handle, service address, account scope and API version. Distinguish those fields from credentials. If a returned URL grants access by possession, describe its handling requirements; do not encourage users to paste it into public support threads.

Our proposed review questions are:

  • Can the reader reopen the guide and identify the same operation without submitting the work again?
  • Does the sample explain what happens when one status read fails?
  • Is the polling policy tied to this service rather than copied from another provider?
  • Can the reader distinguish a local timeout from a terminal operation result?
  • Is an unusually old task something to keep observing, cancel, or escalate under the documented policy?

Do not turn an example loop into an implied promise of unlimited waiting. A production integration needs an owner for unresolved work, even if the server is still processing correctly. The documentation can explain a safe handoff: preserve the handle, record the last confirmed state, and use the service’s supported investigation path.

Consider the user interface too. A message such as “Still processing; you can return using this operation” is more useful when the product really supports that behavior than a spinner with no recovery instruction. That is a design recommendation, not a measured claim about conversion or support savings.

Does cancel mean stop, undo or forget?

Cancellation deserves its own procedure. Google’s shared operation interface describes cancellation as asynchronous and best effort; clients inspect the operation to learn whether it stopped or completed anyway. Its deletion method instead discards interest in the operation result without canceling the work. Some methods may be unsupported. Google operations interface

Microsoft’s architecture pattern proposes a DELETE on the status resource to forward a cancellation instruction, followed by a state update after the back end handles it. It separately asks designers to consider rollback or compensation. Microsoft cancellation guidance

The important difference is semantic. Copying a familiar HTTP verb from another API can produce the wrong instruction. A page should state what the actual endpoint does and what evidence confirms the result.

For your own service, distinguish these user intentions:

User intentionDocumentation must establishOutcome not to promise without evidence
Stop waiting locallyHow to end observation and resume laterServer-side cancellation
Request cancellationSupported method, eligibility and confirmationImmediate termination
Undo completed workSeparate reversal or cleanup procedure, if supportedAutomatic rollback
Remove an operation recordWhich information is removed and what continuesDeletion of the resulting business resource
Remove the resultProduct-specific deletion and retention behaviorErasure of every related record

This is a conceptual checklist, not a suggested endpoint design. A service may support only some of these actions. Clear documentation can say that an action is unavailable.

The most revealing review case is a race: the caller requests cancellation just as work finishes. Ask the implementation owner what the caller can observe and what action is safe next. A screenshot of a successful cancel request does not answer that question.

Also ask about partial effects. If an import already applied some records, does cancellation leave those changes, reverse them, or produce a report for cleanup? Do not equate an operation state with a transaction guarantee. If no atomicity promise exists, the guide should not imply one through phrases such as “cancel to restore everything.”

Give support a compact evidence list: operation identifier, relevant timestamps, last observed state and a redacted response. Credentials and private result URLs should stay out of public examples. The goal is to make investigation possible without teaching readers to disclose more than the support channel needs.

What survives after the operation disappears?

AIP-151 permits completed operation resources to expire and gives 30 days as a rule of thumb. That is design guidance, not a guaranteed retention period for every Google service or every API. AIP-151 expiration

A vanished operation record does not, by itself, explain the status of the business resource. Our recommendation is to document three lifetimes separately when the product has them: the operation record, the result or output resource, and the credential or signed link used to access that result.

For example, an invented export service might retain a job record longer than its download link. A reader opening an old link would need a way to distinguish an expired access mechanism from a deleted export. This is a hypothetical design example, not an observation about any named provider.

Ask the owner to fill in the retention rules, including when each clock starts. Does the period begin on submission, completion, last access or some other event? What does the service return after expiry? Is there a supported lookup or retrieval alternative? If there is no answer, flag an unresolved contract decision instead of inserting a conventional duration.

Retry identity is another lifetime to consider. AIP-155 allows a customer-provided request identifier to support deduplication when the method implements that behavior. The existence of an operation identifier should not be treated as evidence that a separate create request is protected from duplication. Request identification guidance

For documentation purposes, keep two instructions separate: how to recover the outcome of an existing task, and when it is safe to submit a new task. Our earlier API error recovery report covers ambiguous request failures in more detail. Here, the lifecycle guide should link to that policy at the point where observation is no longer possible.

Do not recommend “start over” merely because the UI has forgotten the handle. First determine whether the service offers a supported way to find the original work. If it does not, explain the uncertainty and escalation path. A cleaner screen is not proof that the previous task ceased to exist.

Retention instructions should also cover the reader who returns late. A guide that only works during the first uninterrupted session is incomplete for a workflow intended to survive a browser close or process restart.

Test the whole journey with prepared evidence

The matrix below is our proposed documentation acceptance exercise. We did not execute these scenarios against Google, Microsoft or customer systems. Use synthetic fixtures and an isolated implementation of your own service, with expected behavior approved by its owner.

ScenarioEvidence prepared for the reviewerWhat the guide should let them decide
Submission accepted, work pendingInitial response and a nonterminal statusKeep observing the same task
Status read succeeds, task failsSuccessful read containing terminal failureFollow the operation’s failure path
Caller restartsSaved handle and documented account contextResume observation without duplicate creation
Start permitted, status deniedRestricted-role responsesResolve tracking access without resubmitting
Cancel races with successAccepted cancel request and final successInterpret the actual final state
Partial work remainsTerminal state plus item-level outcome evidenceIdentify what needs cleanup or follow-up
Operation record expiresDocumented expiry response and result policyUse supported recovery or escalation
Polling response is unfamiliarUnexpected body or state fixturePreserve evidence and avoid a false success

Have a reviewer unfamiliar with the implementation use only the published guide and the fixtures. Ask them to explain the next action and the evidence supporting it. Record where they need undocumented knowledge. A test that merely checks for the presence of the word cancel does not establish that the cancellation procedure is usable.

Keep the expected answer attached to the fixture. If a status read is denied, the right action may be to fix permissions, not retry creation. If a local deadline expires, the right interpretation may be unknown, not failed. The acceptance criterion is the correct decision under the documented contract.

Treat partial results explicitly. Google’s import/export guidance, AIP-153, distinguishes these operations and includes partial-failure considerations. That is a reason to ask about item-level outcomes, not evidence that every bulk API has the same guarantees. Import and export guidance

For a bulk workflow, our suggested review record includes the submitted scope, confirmed outcome, any failed or unreported subset, and the supported next action for that subset. Avoid presenting an operation-level success label as proof that every requested item was applied unless the service defines success that way.

If you later measure readers using these exercises, report the task, participant count, environment and definition of success. Do not turn an internal checklist into a percentage claim about documentation quality without collecting reproducible observations.

Publish one connected guide and maintain its decisions

A practical publication structure starts with one task guide, supported by reference pages. The guide explains the intended outcome, required access, submission, observation, completion and recovery. The reference supplies exact fields and response shapes. Neither should require the reader to reconstruct the other from scattered examples.

Our suggested page outline is:

  1. State the result the reader will obtain and the supported environment.
  2. Identify the permissions needed across the journey.
  3. Submit the request and retain the documented tracking information.
  4. Interpret progress and choose the next observation step.
  5. Confirm the terminal outcome and retrieve or inspect the result.
  6. Explain cancellation, late return and unresolved outcomes.

Use a short decision table where prose would otherwise repeat several similar conditions. Keep numeric intervals and retention periods beside their scope. Show whether a number is a default, recommendation, configurable value or hard guarantee. Those labels matter more than making an example look precise.

Assign an internal owner to each lifecycle decision. A change to retention, status authorization or result retrieval can invalidate a guide without changing the initial endpoint schema. Review SDK upgrades and new states for the same reason. Preserve existing URLs when revising the content so users can continue finding the instructions they saved.

When choosing a documentation platform, use this workflow as a content requirement: can it present a connected procedure, readable tables, linked references and clear version context? This report does not rank platforms or claim that a publishing tool can discover undocumented server behavior.

The final editorial check is simple to describe: follow the reader beyond acceptance. Can they leave, return, interpret the outcome and act safely when the expected result is absent? If the guide cannot answer that, another successful request example will not close the gap.

Limitations

This is a synthesis of selected public specifications and provider guidance, not a benchmark of API implementations or documentation effectiveness. Sources were checked on November 20, 2026; pages and product behavior can change. We did not test provider endpoints, cancellation races, permissions or retention. No survey statistic or observed failure rate is asserted. The proposed matrices require service-specific expected results before use. Google guidance, Azure architecture patterns and ARM tracking rules have different scopes; none establishes universal behavior for asynchronous APIs.

Sources

  1. RFC 9110: HTTP Semantics, section 15.3.3IETF / RFC Editor · Accessed 2026-11-20
  2. AIP-151: Long-running operationsGoogle · Accessed 2026-11-20
  3. google.longrunning operations interface and messagesGoogle APIs · Accessed 2026-11-20
  4. Asynchronous Request-Reply patternMicrosoft Learn · Accessed 2026-11-20
  5. Track asynchronous Azure operationsMicrosoft Learn · Accessed 2026-11-20
  6. Polling Long Running OperationsGoogle Cloud · Accessed 2026-11-20
  7. AIP-155: Request identificationGoogle · Accessed 2026-11-20
  8. AIP-153: Import and exportGoogle · Accessed 2026-11-20