A batch get method retrieves multiple specified resources from an API by accepting a list of unique identifiers. Because retrieval is idempotent, it uses HTTP GET; the identifiers therefore travel in the query string rather than a request body. section 18.3.6
Design the operation around these rules:
- Use a parent identifier when all resources belong to one parent. Permit a wildcard parent for cross-parent retrieval only when the long-term storage and distribution costs justify it. section 18.3.6
- Reject conflicting parent values as invalid rather than guessing the caller’s intent. section 18.3.5
- Make the request atomic: an invalid, nonexistent, or unauthorized identifier fails the entire operation instead of producing mixed success and failure. section 18.3.6 section 18.4
Listing 18.6 Example of the batch get method
abstract class ChatRoomApi {
@get("/chatrooms:batchGet")
BatchGetChatRooms(req: BatchGetChatRoomsRequest):
BatchGetChatRoomsResponse;
@get("/{parent=chatRooms/*}/messages:batchGet")
BatchGetMessages(req: BatchGetMessagesRequest):
BatchGetMessagesResponse;
}
interface BatchGetChatRoomsRequest { #1
ids: string[]; #2
}
interface BatchGetChatRoomsResponse {
resources: ChatRoom[]; #3
}
interface BatchGetMessagesRequest {
parent: string; #4
ids: string[]; #2
}
interface BatchGetMessagesResponse {
resources: Message[]; #3
}
The interface pattern separates top-level retrievals, which need only IDs, from child-resource retrievals, which add a parent and return typed resources. section 18.3.6
