A purge method deletes every resource matching a filter in one API call. It combines listing by criteria with batch deletion, so it is useful when the resource identifiers are not known in advance. Because an empty or mistaken filter can match everything, support this custom method only when it is genuinely necessary. section 19.0 section 19.2
Use the purge method with explicit safety rules:
- Require force=true before deleting anything; when force is absent or false, return a preview instead. section 19.3.2
- Return purgeCount and purgeSample so callers can inspect the number of matches and representative resources before execution. section 19.2 section 19.3.2
- Apply filters exactly as the standard list method does, including the behavior that an empty filter matches all resources. section 19.3.1
- Treat the preview as the default operating mode rather than relying on callers to remember a validation-only option. section 19.3.2
Purging matching messages
A chat-room API can expose POST /{parent=chatRooms/*}/messages:purge with a request containing parent, filter, and optional force. A request with force omitted reports the matching count and sample; the same request with force=true deletes those messages. section 19.3.6
Listing 19.2 Minor typos resulting in disastrous consequences
function deleteMatchingMessages(filter: string): number { #1
const result = PurgeMessages({
parent: "chatRooms/1",
filter: fliter, #2
force: true,
});
return result.purgeCount;
}
A one-character variable-name mistake can pass an unintended filter while force=true, illustrating why preview-by-default behavior matters. section 19.3.1
