Designing a REST API

After this lesson, you will be able to: Design REST endpoints with naming conventions, versioning, pagination, filtering, sorting, and nested resources.

Design is what separates pleasant APIs from painful ones. Good design is consistent + predictable; clients can guess the next endpoint correctly.

Prerequisites:HTTP in depth

URL naming conventions

Resources are NOUNS, plural: `/users`, `/posts`, `/orders`. Operations are HTTP VERBS, not in the URL: `POST /users`, not `POST /createUser`. IDs are path segments: `/users/42/posts/7`. Use kebab-case in URLs: `/posted-sessions`, not `/postedSessions`. Lowercase everywhere; HTTPS everywhere.

Common REST patterns

Memorize these shapes.

sql

GET    /users               → list users
GET    /users/42            → get one user
POST   /users               → create a user
PUT    /users/42            → replace user 42 fully
PATCH  /users/42            → partial update
DELETE /users/42            → delete

// Nested resources
GET    /users/42/posts      → posts by user 42
POST   /users/42/posts      → create post for user 42
GET    /users/42/posts/7    → user 42's post 7

// Sub-actions (when REST verbs don't fit cleanly)
POST   /users/42/activate   → trigger activation (use sparingly)
POST   /orders/99/refund    → trigger refund

Pagination

Two strategies. Pick one.

json

// Offset-based (simple; slow on big pages)
GET /posts?page=3&limit=20
GET /posts?offset=40&limit=20

// Response
{
  "data": [ ... ],
  "page": 3,
  "limit": 20,
  "total": 1234,
  "totalPages": 62
}

// Cursor-based (preferred for large datasets + real-time feeds)
GET /posts?cursor=eyJpZCI6MTIzfQ&limit=20

// Response
{
  "data": [ ... ],
  "nextCursor": "eyJpZCI6MTQzfQ",
  "prevCursor": "eyJpZCI6MTAzfQ"
}

// Cursor wins for:
//   - Real-time feeds (new items insert without shifting indices)
//   - Large data (no OFFSET cost)
//   - Stable order (deduplication across pages)

Filtering + sorting via query params

Don't reinvent, follow conventions.

tsx

// Filtering
GET /posts?status=published
GET /posts?status=published&authorId=42
GET /posts?createdAt[gte]=2026-01-01      // ranges with operator suffixes

// Sorting (comma-separated, - for descending)
GET /posts?sort=-createdAt,title

// Field selection (sparse fieldsets, let client ask for less)
GET /users/42?fields=name,email

// Including related resources
GET /posts/7?include=author,comments

// JSON:API spec formalizes all of the above; follow it if you want.

Versioning

Three options. Pick one + commit.

tsx

// Option 1: URL path versioning (most common, easiest to debug)
GET /v1/users
GET /v2/users

// Option 2: Header versioning (cleaner URLs; harder to debug)
GET /users
Header: API-Version: 2

// Option 3: Content-type versioning (purist REST; rarely used)
Accept: application/vnd.myapp.v2+json

// Rules:
//   - Bump version on breaking changes (renamed/removed fields).
//   - Additive changes don't need a version bump.
//   - Document deprecation policy; give clients 6-12 months.

Common mistakes

Verbs in URLs (POST /getUser is wrong; GET /users/42 is right). Mixed plural/singular: /users + /post (consistent plural). OFFSET pagination on infinite-scroll feeds (cursor is better). Skipping versioning (everything is v1 with no path; breaking changes break clients).

←HTTP in Depth

Back to REST APIs

Authentication in REST APIs→