An export method moves resources directly from an API service to external storage, combining resource selection, serialization, optional transformation, and byte transport without an application middleman. It provides a flexible data-moving operation, not a backup or restore mechanism. section 23.0 section 23.2
Design an export method around these practical rules:
- Anchor the method to one resource type and return a long-running operation when exporting may take substantial time. section 23.3.1
- Separate resource selection from output configuration: apply filters before serialization, while OutputConfig controls conversion to bytes, compression, encryption, and the destination. section 23.3.8 section 23.2
- Expect a smear of data unless the underlying storage supports a snapshot or transaction; otherwise concurrent changes can produce no single-point-in-time representation. section 23.3.4
- Preserve identifiers in exported data so the source can be identified later, but do not treat them as a promise that importing will recreate the same resources. section 23.3.5
- Keep exports focused on useful, relatively self-contained resources; handling parent-child graphs or business relationships belongs outside this simple data-moving pattern. section 23.3.6 section 23.4
- Retry failed exports when necessary, recognizing that a later attempt may produce different data and that already-written output may not match the retry. section 23.3.7
Exporting messages from a chat room
A resource-oriented API can expose POST /{parent=chatRooms/*}/messages:export with an ExportMessagesRequest containing the parent, outputConfig, dataDestination, and filter. The operation selects matching Message resources, converts them to the configured serialized format, optionally compresses or encrypts the bytes, and writes them to external storage. If messages change during the export, the result may contain an earlier message, omit a later deletion, or include data from different moments. section 23.3.1 section 23.3.8 section 23.3.4
Listing 23.1 Example of custom import and export methods
abstract class ChatRoomApi {
@post("/{parent=chatRooms/*}/messages:export") #1
ExportMessages(req: ExportMessagesRequest):
Operation<ExportMessagesResponse, ExportMessagesMetadata>;
@post("/{parent=chatRooms/*}/messages:import") #1
ImportMessages(req: ImportMessagesRequest):
Operation<ImportMessagesResponse, ImportMessagesMetadata>;
}
Use the method listing to inspect the resource-scoped route, request type, and long-running export response. section 23.3.1
The central trade-off is simplicity versus guarantees: export methods efficiently bridge one API resource type and external storage, but they provide neither atomic snapshots nor complete restoration. section 23.4 section 23.6
