A metadata interface defines structured information about an API operation itself rather than its final result. Long-running operations use it to expose progress, timestamps, estimated completion, or other status details. section 10.3.5
Design metadata interfaces around information clients can act on:
- Prefer meaningful measurements such as records processed, bytes handled, or estimated completion when a percentage could mislead. section 10.3.5
- Add a Boolean paused field when the operation supports pausing and resuming; do not add pause state universally. section 10.3.7
- Keep metadata separate from the result so clients can inspect progress before the operation completes. section 10.3.5
Analyzing chat messages
AnalyzeMessages returns Operation<MessageAnalysis, AnalyzeMessagesMetadata>. Clients poll GetOperation, read messagesProcessed and messagesCounted, and display progress until done. section 10.3.5
Listing 10.10 Definition of the AnalyzeMessages custom method with metadata type
abstract class ChatRoomApi {
@post("/{parent=chatRooms/*}/messages:analyze")
AnalyzeMessages(req: AnalyzeMessagesRequest):
Operation<MessageAnalysis, AnalyzeMessagesMetadata>;
}
interface AnalyzeMessagesRequest {
parent: string;
}
interface MessageAnalysis { #1
chatRoom: string;
messageCount: number;
participantCount: number;
userGradeLevels: map<string, number>;
}
interface AnalyzeMessagesMetadata { #2
chatRoom: string;
messagesProcessed: number;
messagesCounted: number;
}
Inspect the operation, result, and metadata interface definitions for a concrete progress-reporting API. section 10.3.5
