REST API design has a large body of guidance and a larger body of inconsistent implementations. The design decisions that most affect API consumers and longevity deserve careful treatment.
Consistent error responses
Inconsistent error responses, different JSON shapes for different error types, HTTP status codes that do not reflect the error semantics, error messages that expose internal details, are among the most common API quality problems. The standard: use RFC 7807 (Problem Details for HTTP APIs) as the error response format. A Problem Details response includes type (a URI for the error type), title (human-readable summary), status (HTTP status code), detail (specific explanation), and instance (URI for this specific occurrence).
Cursor-based pagination
Offset-based pagination (page=3&per_page=20) has a known deficiency: insertions before the current offset shift items between pages. A user paginating through a live list sees items repeated or skipped as the list changes. Cursor-based pagination (after=opaque_cursor_string) is position-stable: the cursor encodes the position in the sorted list, not the offset. GitHub's API, Stripe's API, and the Relay cursor connection specification all use cursor-based pagination.
HATEOAS in practice
HATEOAS (Hypermedia as the Engine of Application State) includes links in API responses that describe available state transitions: a resource response includes links for 'update', 'delete', 'related-resources'. The promise is that clients can discover available operations from the response without hardcoded URL construction. In practice, most API consumers hardcode URLs anyway, and HATEOAS adds response payload overhead. The pragmatic approach: include self links for resource identifiers, skip the full HATEOAS link graph for most APIs.
Idempotency keys
POST operations that create resources are not idempotent by default. A network timeout on a POST request leaves the client uncertain whether the resource was created. Idempotency keys (a client-generated UUID sent in the Idempotency-Key header) allow the server to deduplicate requests: if the same key is seen again within a retention window, return the original response without re-executing the operation. Stripe's API popularised this pattern; it is essential for payment and order creation APIs.