REST API Design Basics

Resources and methods#

Name endpoints after resources (plural nouns) and let the HTTP method express the action. Idempotent methods can be retried safely after a timeout.

Status codes that carry meaning#

One error format everywhere#

Use the same shape for every error so clients can handle them generically. RFC 9457 (Problem Details) is a widely supported standard.

1{2  "type": "https://api.example.com/problems/validation",3  "title": "Validation failed",4  "status": 422,5  "errors": [6    { "field": "email", "message": "Must be a valid email address" }7  ]8}

Cursor pagination#

Offset pagination (?page=3) skips or repeats items when rows are inserted. A cursor points at the last item seen, so pages stay stable and queries stay fast on large tables.

1{2  "data": [3    { "id": "ord_11", "total": 4900 },4    { "id": "ord_12", "total": 1200 }5  ],6  "nextCursor": "b3JkXzEy",7  "hasMore": true8}