A list method returns the resources belonging to a specified collection. Unlike a get method, it targets a collection rather than one resource, such as chatRooms or a ChatRoom’s messages. section 7.3.4
A collection may be top-level or nested under a parent resource. Listing ChatRoom resources targets chatRooms; listing messages for one ChatRoom targets that resource’s messages subcollection. section 7.3.4
Listing 7.2 An example of the standard list method
abstract class ChatRoomApi {
@get("/chatRooms") #1
ListChatRooms(req: ListChatRoomsRequest): ListChatRoomsResponse;
@get("/{parent=chatRooms/*}/messages") #2
ListMessages(req: ListMessagesRequest): ListMessagesResponse;
}
interface ListChatRoomsRequest {
filter: string;
}
interface ListChatRoomsResponse {
results: ChatRoom[];
}
interface ListMessagesRequest {
parent: string;
filter: string;
}
interface ListMessagesResponse {
results: Message[];
}
The API shape shows top-level and nested list methods, request filters, and array-based results. section 7.3.4
Design list methods around these practical rules:
- Return only resources the requester can access; different requesters may receive different views of the same collection. section 7.3.4
- Support filtering when callers need a subset of a collection, and keep filtering distinct from other result-set controls. section 22.0 section 25.3.2
- Use pagination for associated-resource listings and avoid result counts or custom sorting in a standard list method. section 7.5 section 15.3.1
- When soft deletion is enabled, exclude deleted resources by default and provide an explicit includeDeleted option. section 25.3.2
Discovering long-running operations
An operations list method lets callers find ongoing or paused Operation resources without knowing their identifiers. Its filter must support status and resource metadata, such as asking which operations are not done or paused. section 10.3.8
Viewing soft-deleted resources
A request such as ListChatRooms({ filter: "deleted: true", includeDeleted: true }) explicitly asks for deleted resources while preserving the default behavior of hiding them. section 25.3.2
