API Design: Stable Contracts and Predictable Errors

What it does

ECC’s API design source brings resource naming, HTTP semantics, response envelopes and access controls into one review. Its useful starting point is a client-visible contract: which resource is addressed, what an operation means and how success or failure is represented. It discusses offset and cursor pagination, filtering, sorting, versioning and rate-limit feedback, with examples across several server stacks. The guide is most valuable before a public endpoint becomes difficult to change. Its framework examples are illustrations rather than a requirement to introduce a new server or response wrapper into an established application.

When to use it

• Define an order-history endpoint consumed by both a dashboard and an export job.
• Replace inconsistent validation failures with field-level errors that clients can handle.
• Review a growing list endpoint whose offset pagination becomes unstable as records arrive.

Step-by-step workflow

1. Inspect existing routes and consumers; record compatibility requirements and the resource relationships before naming new endpoints.
2. Specify methods, success codes, error fields and authorization decisions, including missing records and access to another account’s object.
3. Choose pagination using real ordering and update behavior; bound page sizes and allowlist filter and sort fields.
4. Write representative request and response examples, including an invalid cursor, exhausted rate limit and malformed input.
5. Implement the smallest compatible change and verify the contract from a consumer’s perspective, documenting any migration window.

Example request

Review the proposed GET /v1/orders contract for our account dashboard. Use our existing JSON error shape. Orders arrive while users paginate, so propose a deterministic cursor with a unique tie-breaker and a maximum page size. Show an empty result, an invalid cursor, forbidden cross-account access and rate-limit feedback. State whether a cursor is opaque and what happens if the referenced order disappears. Do not rename existing fields without a compatibility plan. Deliver the contract and a focused set of acceptance cases before implementation.

Worked example

Consider two orders created at the same timestamp. A cursor based only on that timestamp can skip one or repeat it on the next page. The reviewed design therefore needs an explicit secondary key, with matching query ordering and a cursor that is validated at the boundary. A test inserts another order between page requests and checks the chosen consistency contract. A separate account attempts to reuse the cursor; authorization still scopes the query independently. The resulting documentation explains behavior during concurrent writes rather than promising a frozen snapshot the storage system does not provide.

What you get

A route and schema proposal, example payloads, failure semantics, pagination rules and a compatibility checklist tied to actual consumers.

How to evaluate the result

• Each status code matches the documented operation and failure.
• Concurrent inserts and tied sort values do not violate the chosen pagination contract.
• Cross-account requests fail even when resource IDs or cursors are valid.

What you need

Access to route definitions, authentication rules, database ordering and at least one real consumer. The implementation language can differ from the source examples.

Setup and activation

The reviewed ECC source provides an .agents skill layout. Consult the repository README for the chosen client, retain referenced supporting files and explicitly activate only the workflow needed. This catalogue read source files; it installed and executed nothing. Client compatibility depends on available tools and instruction loading, and was not runtime-tested here. Before installation, scan the exact source version, review permissions and use disposable non-sensitive examples.

Limits and considerations

Uniform envelopes are not automatically better than an established client contract. Cursor pagination needs a stable ordering and does not create snapshot isolation. Never accept arbitrary database field names from filtering parameters or treat possession of an object identifier as authorization.

Related workflows

• Use Backend Patterns to implement the validated contract.
• Use E2E Testing to check a critical client journey.

License and reuse

MIT in the selected SKILL.md and repository LICENSE. Preserve notices; external packages, services and example dependencies retain their own terms.

Further reading

• Reviewed skill at immutable commit
• Reviewed publisher README
• Reviewed MIT license