A long-running task is an API operation whose completion is delayed while work continues in the background. Instead of making callers wait for a final response, the method returns an operation resource that eventually resolves with a result or an error. This gives clients a consistent way to check progress, wait for completion, receive notification, and sometimes cancel, pause, or resume work. section 10.0 section 10.2
Design the operation as a durable, inspectable API resource:
- Return an operation containing an identifier, a done flag, an optional typed result or error, and optional typed metadata. section 10.3.1
- Use metadata for progress information such as counts, percentages, or estimated time remaining rather than exposing an unstructured value. section 10.3.1
- Persist operations in a centralized top-level collection such as /operations/1, allowing individual lookup and system-wide discovery. section 10.3.2
- Expose polling or blocking access to status, and use custom methods for cancellation, pausing, or resuming when the underlying work supports them. section 10.0 section 10.3.7
- Treat pausing as capability-specific: represent paused state in metadata instead of adding a universal field that every operation would have to support. section 10.3.7
- Expire stored operations after a standard period, since persistence supports remote recovery but does not require indefinite retention. section 10.6
Asynchronous message export
A ChatRoom API can expose ExportMessages as a custom method returning Operation<ExportMessagesResponse, ExportMessagesMetadata>. The request starts the export quickly, while clients poll the operation or wait for its eventual response; metadata can report progress, and the operation can resolve with either the export response or an OperationError. section 23.3.1
Listing 10.4 Definition of the Operation and OperationError interfaces
interface Operation<ResultT, MetadataT> { #1
id: string;
done: boolean; #2
result?: ResultT | OperationError; #1
metadata?: MetadataT; #1
}
interface OperationError {
code: string;
message: string;
details?: any;
}
Inspect the generic Operation and OperationError interfaces, including identifiers, completion state, typed results, errors, and metadata. section 10.3.1
