Skip to main content
Technology & EngineeringAPI Design29 lines

Choose REST or RPC and Design Batch Outcomes

Decide between resource-oriented and operation-oriented APIs, then specify atomic or partial batch results and safe retry semantics.

Quick Summary9 lines
Write down the client’s real goal and the state it needs to discover. A resource-oriented contract fits an identifiable collection or document with stable operations and representations. An operation-oriented contract can fit a domain action with its own inputs, states, or results, such as recalculating a statement. An action can still be represented as a job resource when callers need a receipt, polling or cancellation. Prefer a contract that makes client recovery understandable. Use links for available transitions when clients need to discover them at runtime, and document relation meanings and authorization.

## Key Points

- [Fielding REST architectural style](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
- [RFC 4918 Multi-Status](https://www.rfc-editor.org/rfc/rfc4918#section-13)
- [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457)
skilldb get api-design-skills/api-contracts-and-batch-outcomesFull skill: 29 lines
Paste into your CLAUDE.md or agent config

Choose REST or RPC and Design Batch Outcomes

Decide what the caller manipulates

Write down the client’s real goal and the state it needs to discover. A resource-oriented contract fits an identifiable collection or document with stable operations and representations. An operation-oriented contract can fit a domain action with its own inputs, states, or results, such as recalculating a statement. An action can still be represented as a job resource when callers need a receipt, polling or cancellation. Prefer a contract that makes client recovery understandable. Use links for available transitions when clients need to discover them at runtime, and document relation meanings and authorization.

For a sample bulk archive, define a caller-owned batch ID or idempotency key and a distinct stable ID per item. Choose an atomic batch when success requires all-or-nothing state. If items are independent, define a per-item outcome with its identifier, resulting state, and machine-readable failure code. Document duplicate input, ordering, empty lists and resource limits. State whether results are returned immediately or through a job URL.

Make partial success explicit

Specify what the outer status represents. A successfully accepted asynchronous job can return an accepted status while the job later reports failures. A completed synchronous JSON batch can report its processing result and per-item statuses in a documented envelope. A request that cannot be parsed or authorized uses the ordinary request-level error response. Prefer an established schema such as Problem Details for request-level errors where it matches the API.

The standardized 207 Multi-Status response comes from WebDAV. Its response body and resource-level status semantics are defined there. For a non-WebDAV JSON API, avoid assuming clients understand WebDAV behavior. Define any custom status and media type together, or choose a documented ordinary status and a JSON envelope. Explicitly say whether a retry should repeat the whole batch or only retryable items.

Test recovery and compatibility

Run a fixture with three targets: valid, missing, and already in the requested state. Verify actual state afterward, not merely the status code. Repeat the request with the same key, then with changed content under that key. Confirm the contract differentiates a replay from a conflicting request. Exercise a timeout after a write and show which receipt or lookup establishes the result. Keep pagination, rate limits and version negotiation consistent with the rest of the API. Record the behavior that must remain compatible and test an existing client against the change.

References

Install this skill directly: skilldb add api-design-skills

Get CLI access →