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.
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:
| Layer | Question the reader needs answered | Evidence to specify |
|---|---|---|
| Submission | Was the request accepted or rejected? | Initial response and its exact meaning |
| Operation | Which task is being tracked? | Durable identifier and supported lookup route |
| Progress | Is there more work to wait for? | Documented nonterminal states and observation rules |
| Outcome | Did this task succeed, fail or stop? | Terminal state and result or error representation |
| Use | Can 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 item | Record for this endpoint | Avoid assuming |
|---|---|---|
| Tracking handle | Exact field or header and its scope | Every operation uses Location |
| State interpretation | Terminal and nonterminal values | HTTP success means job success |
| Authorization | Permissions for start, observe and retrieve | The same permission covers all three |
| Result | Inline result, resource address or another step | A completion flag contains the deliverable |
| Unknown values | Supported fallback and escalation | An 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 intention | Documentation must establish | Outcome not to promise without evidence |
|---|---|---|
| Stop waiting locally | How to end observation and resume later | Server-side cancellation |
| Request cancellation | Supported method, eligibility and confirmation | Immediate termination |
| Undo completed work | Separate reversal or cleanup procedure, if supported | Automatic rollback |
| Remove an operation record | Which information is removed and what continues | Deletion of the resulting business resource |
| Remove the result | Product-specific deletion and retention behavior | Erasure 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.
| Scenario | Evidence prepared for the reviewer | What the guide should let them decide |
|---|---|---|
| Submission accepted, work pending | Initial response and a nonterminal status | Keep observing the same task |
| Status read succeeds, task fails | Successful read containing terminal failure | Follow the operation’s failure path |
| Caller restarts | Saved handle and documented account context | Resume observation without duplicate creation |
| Start permitted, status denied | Restricted-role responses | Resolve tracking access without resubmitting |
| Cancel races with success | Accepted cancel request and final success | Interpret the actual final state |
| Partial work remains | Terminal state plus item-level outcome evidence | Identify what needs cleanup or follow-up |
| Operation record expires | Documented expiry response and result policy | Use supported recovery or escalation |
| Polling response is unfamiliar | Unexpected body or state fixture | Preserve 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:
- State the result the reader will obtain and the supported environment.
- Identify the permissions needed across the journey.
- Submit the request and retain the documented tracking information.
- Interpret progress and choose the next observation step.
- Confirm the terminal outcome and retrieve or inspect the result.
- 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
- RFC 9110: HTTP Semantics, section 15.3.3IETF / RFC Editor · Accessed 2026-11-20
- AIP-151: Long-running operationsGoogle · Accessed 2026-11-20
- google.longrunning operations interface and messagesGoogle APIs · Accessed 2026-11-20
- Asynchronous Request-Reply patternMicrosoft Learn · Accessed 2026-11-20
- Track asynchronous Azure operationsMicrosoft Learn · Accessed 2026-11-20
- Polling Long Running OperationsGoogle Cloud · Accessed 2026-11-20
- AIP-155: Request identificationGoogle · Accessed 2026-11-20
- AIP-153: Import and exportGoogle · Accessed 2026-11-20