Principle Api Design

API Design

An API is a contract. Breaking it breaks callers. Design for evolvability from day one.

Contract-First

Design the interface before the implementation. Write the schema or proto before any code.

• Contracts force clarity on resource modeling, field names, and error cases early.
• If the design is painful to describe, the implementation will be painful to use.
• API review at design time is cheap; API review after clients exist is very expensive.

Versioning

Every breaking change requires a new version. Communicate it, window it, enforce the schedule.

• Breaking: removing a field, changing a field type, changing semantics of a status code, renaming a resource.
• Additive (non-breaking): new optional fields, new endpoints, new enum values in response.
• URL-path versioning (/v1/orders) — visible, cacheable, easy to route; good for major versions.
• Header versioning (API-Version: 2024-01-01) — cleaner URLs; common for date-based schemes.
• Set a deprecation window (minimum 6 months for external APIs) and enforce it; sunset headers signal the date.

Idempotency

Operations must be safe to retry. Network failures happen; callers will retry.

• Safe (GET, HEAD, OPTIONS) — no side effects.
• Idempotent (PUT, DELETE) — repeating produces the same result.
• Non-idempotent (POST) — accept an idempotency key header; server deduplicates by key.
• Key scope: client-generated UUID, tied to the logical operation, expires after a defined window.
• Return the same response for a duplicate key — do not create twice, do not error.

Pagination

Never return unbounded collections. Choose the model based on query patterns.

• Offset pagination — simple; breaks when records insert or delete during traversal; fine for small, stable sets.
• Cursor pagination — stable under concurrent writes; opaque cursor encodes position; cannot jump to page N.
• Always cap page size server-side; document the default and maximum.
• Return a next_cursor or next_page token — do not expose the underlying query offset or row ID.

Error Shapes

Consistent error envelopes let callers handle errors generically.

• Every error response: code (machine-readable), message (human-readable), details (optional array), request_id.
• HTTP status discipline: 400 bad input, 401 unauthenticated, 403 unauthorized, 404 not found, 409 conflict, 422 semantic error, 429 rate limited, 500 server fault.
• Problem+JSON (RFC 7807) as a standard envelope for REST APIs.
• Never return 200 OK with "error": true in the body — callers cannot detect errors without body parsing.

Evolvability

Design for forward and backward compatibility from the start.

• Additive only — add fields, never remove or rename in-place.
• Tolerate unknown fields — clients must ignore keys they do not recognize (Postel's law on reading).
• Default-on-omit — if a field is absent, apply a safe default; do not error.
• Never reuse a retired field name with a different type or semantic.
• Serialize enums as strings, not integers — new values are additive; integer reordering is breaking.

REST vs RPC vs Event-Driven

REST

• Use when: resource-oriented CRUD, public APIs, cache-friendly reads, diverse client ecosystem.
• Costs: round trips for complex operations; HTTP overhead; no native streaming.
• Don't use when: low-latency internal services, server-push streaming, or highly procedural workflows.

RPC (gRPC / Thrift / Twirp)

• Use when: internal service-to-service, schema-first contracts, strong typing required, streaming needed.
• Costs: less human-readable; requires code generation; harder to debug with standard HTTP tools.
• Don't use when: public APIs consumed by browsers or third parties that lack generated client support.

Event-Driven

• Use when: decoupled producers and consumers, eventual consistency acceptable, audit log or replay required.
• Costs: ordering guarantees complex; debugging harder; silent consumer drift possible.
• Don't use when: synchronous response is required, or consumer must confirm processing before producer continues.

When Strict API Discipline is Overkill

• Internal-only APIs with a single consumer owned by the same team.
• Short-lived prototypes (under two weeks) with no external consumers.
• Scripts or migrations that call an API once and are immediately discarded.

Red Flags

| Flag | Problem | |------|---------| | /v1/, /v1.1/, /v2/, /v2-new/ in one codebase | Version creep — no deprecation discipline enforced | | Breaking field removed in a patch release | Breaking change shipped without a version bump | | Response fields map directly to DB column names | Schema leak — any migration breaks clients | | 200 OK with {"error": true} in body | Generic error handling impossible for callers | | GET endpoint that creates or modifies state | Violates HTTP safety; CDNs and browsers will cache the write | | No request_id in error responses | Cannot correlate support reports to server logs |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lugassawan
• Source: lugassawan/swe-workbench
• License: MIT

Install and usage instructions live in the source repository linked above.