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.
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 linesChoose 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
Related Skills
API Documentation
OpenAPI and Swagger documentation practices for generating accurate, maintainable API references
API Error Handling
Error response design and HTTP status code conventions for consistent, actionable API error reporting
API Pagination
Pagination patterns including cursor-based, offset, and keyset pagination for efficient list endpoints
API Versioning
API versioning strategies for evolving APIs without breaking existing consumers
GRAPHQL Design
GraphQL schema design patterns for building flexible, efficient, and evolvable query APIs
REST Design
RESTful API design principles for building consistent, intuitive, and scalable HTTP APIs