System Design: API Design

Introduction

Endpoint naming, versioning, and request-response structure are your communication contract. Poor API design means broken integrations, fragile mobile clients, and expensive version migrations.

This guide covers practical REST design with an interactive contract explorer — toggle API versions and compare payloads side by side.

← Back to System Design overview

Design principles

Resource-oriented URLs

Use nouns, not verbs:

GET    /api/v2/users
POST   /api/v2/orders
GET    /api/v2/orders/{id}
PATCH  /api/v2/orders/{id}

Avoid /getUser, /createOrder — HTTP methods already express the action.

Versioning

Request and response shape

Consistent envelopes help clients:

{
  "data": {},
  "error": null,
  "meta": { "requestId": "req_abc" }
}

Errors should be machine-readable:

{
  "error": {
    "code": "ORDER_INVALID_ITEMS",
    "message": "Line items cannot be empty",
    "field": "lineItems"
  }
}

Interactive contract explorer

Switch between v1 and v2 to see how naming and pagination evolve without breaking the mental model.

Query: ?cursor=abc&limit=20

{
  "data": [{ "id": "usr_1", "fullName": "Asha" }],
  "nextCursor": "def"
}

Pagination patterns

Offset (?page=2&limit=20) — simple, but slow on large tables.

Cursor (?cursor=abc&limit=20) — stable for feeds and real-time inserts; preferred at scale.

Idempotency and safety

POST creates resources. For payments and orders, accept an Idempotency-Key header so retries do not double-charge.

POST /api/v2/orders
Idempotency-Key: 7f3c9a2e-...

Back to index