APIs & REST Deep Dive

The Big Picture

Every REST interaction follows the same pattern: a client sends an HTTP request to a server, and the server sends back an HTTP response. That's it. Everything else is just details about what goes inside those two messages.

HTTP Methods

HTTP methods tell the server what you want to do with a resource. Think of them as verbs: you GET data, POST new data, PUT updated data, and DELETE data. There are five you need to know cold.

Status Codes

Status codes are the server's way of saying "here's what happened." They're grouped into five families, but you only need to memorize about 15 to handle 99% of real-world situations.

2xx — Success

The request worked. Celebrate.

3xx — Redirect

The resource moved. Follow the breadcrumbs.

4xx — Client Error

You messed up. Fix your request.

5xx — Server Error

The server messed up. Not your fault (usually).

Request & Response Anatomy

Let's dissect a real HTTP exchange. Every request and response follows the same structure: a start line, headers, and an optional body. Once you see the pattern, it never changes.

The Request

Here's a POST request to create a new user, sent via curl:

curl -X POST https://api.example.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "name": "Alice Johnson",
    "email": "[email protected]",
    "role": "admin"
  }'

Breaking that down:

• Method + URL: POST /api/users — "create a new user"
• Content-Type header: tells the server the body is JSON
• Authorization header: proves who you are (Bearer token)
• Body: the actual data you're sending (JSON)

The Response

{
  "status": 201,
  "headers": {
    "Content-Type": "application/json",
    "Location": "/api/users/128",
    "X-Request-Id": "req_abc123"
  },
  "body": {
    "id": 128,
    "name": "Alice Johnson",
    "email": "[email protected]",
    "role": "admin",
    "createdAt": "2026-04-01T10:30:00Z"
  }
}

Breaking that down:

• Status 201: "Created" — the user was successfully created
• Location header: where the new resource lives
• X-Request-Id: a tracking ID for debugging (extremely useful in production)
• Body: the created resource, including server-generated fields (id, createdAt)

Designing REST Endpoints

Good endpoint design makes your API intuitive. Bad endpoint design makes your API a guessing game. Here are the rules that separate the two.

The Three Rules

1. Use nouns, not verbs. The HTTP method IS the verb. The URL is the noun.
2. Use plural resource names. /users, not /user. Even when fetching one.
3. Nest for relationships. /users/42/posts = "posts belonging to user 42."

Good vs Bad Endpoint Design

Path Params vs Query Params

Use path parameters to identify a specific resource. Use query parameters to filter, sort, or paginate a collection.

• /api/users/42 — path param identifies user 42
• /api/users?role=admin&sort=name — query params filter and sort the collection

Full CRUD Route Set

Here's what a complete set of CRUD routes looks like for a /api/users resource:

# List all users (with optional filters)
GET    /api/users?page=1&limit=20&role=admin

# Get a single user by ID
GET    /api/users/42

# Create a new user
POST   /api/users

# Replace user entirely
PUT    /api/users/42

# Partially update a user
PATCH  /api/users/42

# Delete a user
DELETE /api/users/42

# Get posts belonging to user 42
GET    /api/users/42/posts

Pagination, Filtering & Sorting

Any API that returns collections needs pagination. Without it, a "get all users" request with a million rows will crash your server and your client. There are two main approaches, and choosing the right one matters.

Offset vs Cursor Pagination

Offset Pagination Example

# Request: page 3, 20 items per page
GET /api/books?page=3&limit=20&sort=title&order=asc

{
  "data": [
    { "id": 41, "title": "Clean Code" },
    { "id": 42, "title": "Code Complete" }
  ],
  "pagination": {
    "page": 3,
    "limit": 20,
    "total": 487,
    "totalPages": 25
  }
}

Cursor Pagination Example

# Request: next 20 items after cursor
GET /api/books?cursor=eyJpZCI6NDB9&limit=20

{
  "data": [
    { "id": 41, "title": "Clean Code" },
    { "id": 42, "title": "Code Complete" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6NjB9",
    "hasMore": true
  }
}

Error Handling

Every API will have errors. The difference between a good API and a frustrating one is how predictably those errors are communicated. The goal: every error response should have the same shape, so clients can parse errors with a single handler.

Standard Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      },
      {
        "field": "age",
        "message": "Must be a positive integer"
      }
    ],
    "requestId": "req_abc123",
    "timestamp": "2026-04-01T10:30:00Z"
  }
}

The structure follows a simple contract:

• code: A machine-readable string (not the HTTP status — that's already in the response header). Examples: VALIDATION_ERROR, RESOURCE_NOT_FOUND, RATE_LIMIT_EXCEEDED.
• message: A human-readable summary.
• details: An array of specific problems (especially useful for validation).
• requestId: For tracing in logs.

Error Response Examples by Status Code

// 401 Unauthorized
{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Missing or invalid Bearer token",
    "requestId": "req_xyz789"
  }
}

// 404 Not Found
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with id 999 does not exist",
    "requestId": "req_def456"
  }
}

// 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You've exceeded 100 requests per minute",
    "retryAfter": 32,
    "requestId": "req_ghi012"
  }
}

API Versioning

APIs evolve. Fields get renamed, endpoints get deprecated, response shapes change. Versioning lets you make breaking changes without breaking existing clients. There are three main strategies.

Real-World Example: Bookstore API

Let's tie everything together with a complete mini API for a bookstore. Five endpoints, full request/response examples, proper status codes, and consistent error handling.

Endpoint 1: List All Books

# Request
GET /api/v1/books?page=1&limit=10&genre=fiction&sort=title

{
  "data": [
    {
      "id": 1,
      "title": "The Great Gatsby",
      "author": "F. Scott Fitzgerald",
      "genre": "fiction",
      "price": 12.99,
      "isbn": "978-0743273565"
    },
    {
      "id": 2,
      "title": "To Kill a Mockingbird",
      "author": "Harper Lee",
      "genre": "fiction",
      "price": 14.99,
      "isbn": "978-0061120084"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "totalPages": 5
  }
}

Endpoint 2: Get a Single Book

# Request
GET /api/v1/books/1

{
  "id": 1,
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "genre": "fiction",
  "price": 12.99,
  "isbn": "978-0743273565",
  "publishedDate": "1925-04-10",
  "pageCount": 180,
  "description": "A story of the mysteriously wealthy Jay Gatsby...",
  "createdAt": "2026-03-15T08:00:00Z",
  "updatedAt": "2026-03-15T08:00:00Z"
}

Endpoint 3: Create a New Book

# Request
curl -X POST /api/v1/books \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "title": "Clean Code",
    "author": "Robert C. Martin",
    "genre": "technical",
    "price": 34.99,
    "isbn": "978-0132350884"
  }'

// Response: 201 Created
// Location: /api/v1/books/48
{
  "id": 48,
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "genre": "technical",
  "price": 34.99,
  "isbn": "978-0132350884",
  "createdAt": "2026-04-01T10:30:00Z",
  "updatedAt": "2026-04-01T10:30:00Z"
}

Endpoint 4: Update a Book (PATCH)

# Request: only updating the price
curl -X PATCH /api/v1/books/48 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{ "price": 29.99 }'

// Response: 200 OK
{
  "id": 48,
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "genre": "technical",
  "price": 29.99,
  "isbn": "978-0132350884",
  "createdAt": "2026-04-01T10:30:00Z",
  "updatedAt": "2026-04-01T11:15:00Z"
}

Endpoint 5: Delete a Book

# Request
curl -X DELETE /api/v1/books/48 \
  -H "Authorization: Bearer eyJhbGci..."

// Response: 204 No Content
// (empty body)

And when things go wrong:

// POST /api/v1/books with missing required field
// Response: 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "title", "message": "Title is required" },
      { "field": "isbn", "message": "ISBN must be a valid ISBN-13 format" }
    ],
    "requestId": "req_book_001"
  }
}