Write method

As explained in API Design Patterns

A write method is an API operation that adds entries to a collection or submits data for streaming processing without creating a resource representation.

A write method ingests entries without creating individually addressable resources. It suits anonymous or ephemeral data that users read through aggregates such as counts, averages, or dashboard statistics. section 20.2 section 20.6

Design a write method around these rules:

• Return only success or failure status; return no resource and normally no long-running-operation resource. section 20.3 section 20.6
• Model the payload as an entry rather than a resource, usually by renaming the create request's resource field to entry. section 20.3
• Bind the method to the target collection, such as /chatRooms/1/statEntries:write, rather than to the parent resource. section 20.3
• Permit immediate responses before aggregate data becomes visible when ingestion uses delayed analytics processing and eventual consistency. section 20.3.1

Writing a chat-room statistic

A request can target a chat-room statistics collection and carry an entry: parent: "chatRooms/1"; entry: ChatRoomStatEntry. The method acknowledges acceptance with a status code, while later reads retrieve aggregate statistics rather than this entry. section 20.3 section 20.2

Figure 20.1 Sequence of events for the write method

Use the sequence diagram to trace entry submission, processing, and aggregate reading. section 20.2

How API Design Patterns covers it

How deep it goes

Defines payloads, return behavior, URL binding, and consistency trade-offs, but does not detail processing implementation.

Examples

Uses chat-room statistics, ChatRoomStatEntry requests, sequence diagrams, counters, moving averages, and dashboard aggregates.

What it assumes

Assumes familiarity with create methods, collections, resources, aggregate reads, and long-running operations.

What you can do after

Operate/configure an anonymous ingestion endpoint with entry payloads, collection-oriented URLs, status-only responses, and eventual consistency.

How it connects

Connects anonymous entries with create methods, aggregate reads, batch writes, purge methods, and eventual consistency.

liveBookmanning.com

Read API Design Patterns on liveBook Get the book at manning.com

Related concepts

• custom methodkind of · A custom method is a user-defined operation or capability added to an interface to provide behavior beyond its predefined functionality.
• void typeconfigures · A void type is a type or return designation indicating that an operation produces no meaningful value for its caller.
• redundancyaddresses · Redundancy is the presence of duplicate or overlapping information, components, or resources, whether intentional or unnecessary.
• create methodcontrasts with · A create method is an API operation that creates a new resource or domain entity from client-supplied input.
• long-running taskalternative to · A long-running task is a work item or operation whose execution takes an extended time relative to surrounding program flow.
• operationcontrasts with · An operation is an action or computation performed by or through a system, object, or interface, often producing a result or effect.

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.