Filtering selects only resources matching stated conditions before an API returns or processes them. Server-side filtering avoids fetching and evaluating an entire collection on the client, reducing network and processing waste. section 22.1 section 22.2
Use filtering deliberately in standard list methods:
- Add a filter field to the list request and evaluate it before returning results. section 22.3.3
- Represent the filter as a string following documented syntax rather than a rigid client-side schema, preserving room for future extensions. section 7.3.4 section 22.3.1
- Keep evaluation scoped to a single resource, reject positional comparisons in repeated fields, and surface evaluation errors immediately. section 22.6
- Document only useful operations, adding functions when basic comparisons cannot express required intent instead of opening unrestricted query behavior. section 22.2 section 22.6
Filtering a chat-room list
A list endpoint can accept a request such as { filter: "title = \"New Chat!\"" } and return only matching ChatRoom resources. The same intent can be expressed with a structured MongoDB-style query, but a string keeps the public request shape less coupled to an evolving schema. section 22.3.1 section 23.3.8
Filtering also supports operational workflows: listing operations can find unfinished or paused work and query operation metadata. Export methods can filter resources before serialization, while keeping selection separate from output configuration. section 10.3.8 section 23.3.8
Listing 22.8 Final API definition
abstract class ChatRoomApi {
@get("/chatRooms")
ListChatRooms(req: ListChatRoomsRequest): ListChatRoomsResponse;
}
interface ListChatRoomsRequest {
filter: string;
maxPageSize: number;
pageToken: string;
}
interface ListChatRoomsResponse {
results: ChatRoom[];
nextPageToken: string;
}
Inspect the compact list-request definition showing filter alongside pagination fields and the paginated response. section 22.3.3
