Introduction to
REST API Design

REpresentational State Transfer was defined by Roy Fielding in his 2000 doctoral dissertation. It is an architectural style, not a protocol or specification. REST describes how distributed hypermedia systems should behave when designed well.

A REST API exposes resources (nouns) at stable URIs and lets clients manipulate them using standard HTTP methods (verbs). The server transfers representations of resource state — typically JSON.

# Good URL patterns
GET    /api/v1/users              # list users
GET    /api/v1/users/42           # single user
GET    /api/v1/users/42/orders    # user's orders
POST   /api/v1/users              # create user
DELETE /api/v1/users/42           # delete user

# Bad URL patterns
GET    /api/v1/getUser?id=42      # verb in URL
POST   /api/v1/user/create        # verb + singular
GET    /api/v1/users/42/orders/7/items/3/tags  # too deep

// POST /api/v1/users — request body
{
  "firstName": "Alice",
  "lastName": "Chen",
  "email": "alice@example.com",
  "role": "editor"
}

// Response — single resource
{
  "data": {
    "id": 42,
    "firstName": "Alice",
    "lastName": "Chen",
    "email": "alice@example.com",
    "role": "editor",
    "createdAt": "2025-03-15T10:30:00Z"
  }
}

// Response — collection with metadata
{
  "data": [
    { "id": 1, "name": "Widget A" },
    { "id": 2, "name": "Widget B" }
  ],
  "meta": {
    "totalCount": 87,
    "page": 1,
    "perPage": 25,
    "totalPages": 4
  },
  "links": {
    "self":  "/api/v1/products?page=1",
    "next":  "/api/v1/products?page=2",
    "last":  "/api/v1/products?page=4"
  }
}

// 422 Unprocessable Entity
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body contains invalid fields",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "message": "must be a valid email address",
      "value": "not-an-email"
    },
    {
      "field": "age",
      "message": "must be at least 18",
      "value": 12
    }
  ]
}

// Express error handler
app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  res.status(status).json({
    type: `https://api.example.com/errors/${err.code}`,
    title: err.title || 'Internal Server Error',
    status,
    detail: status === 500
      ? 'An unexpected error occurred'
      : err.message,
    instance: req.originalUrl,
    ...(err.errors && { errors: err.errors })
  });
});

# Simple equality
GET /api/v1/products?category=electronics&in_stock=true

# Operator suffixes
GET /api/v1/products?price_gte=10&price_lte=100

# Bracket notation (JSON:API style)
GET /api/v1/products?filter[price][gte]=10&filter[price][lte]=100

# Search
GET /api/v1/products?q=wireless+headphones

# Only return id, name, and price
GET /api/v1/products?fields=id,name,price

# JSON:API style
GET /api/v1/products?fields[products]=id,name,price

# Sort by created_at descending, then name ascending
GET /api/v1/products?sort=-created_at,name

# Explicit direction style
GET /api/v1/products?sort=created_at:desc,name:asc

// Express query parser
const allowedSort = ['name', 'price', 'created_at'];
const sortField = allowedSort.includes(req.query.sort)
  ? req.query.sort : 'created_at';
const order = req.query.order === 'desc' ? 'DESC' : 'ASC';
const results = await db.query(
  `SELECT * FROM products ORDER BY ${sortField} ${order}`
);

# API Key (header)
GET /api/v1/data
X-API-Key: sk_live_abc123def456

# Bearer Token (JWT)
GET /api/v1/users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Basic Auth
GET /api/v1/admin
Authorization: Basic YWRtaW46cGFzc3dvcmQ=

// JWT middleware in Express
const jwt = require('jsonwebtoken');

function authenticate(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({
      type: '/errors/unauthorized',
      title: 'Missing or invalid token',
      status: 401
    });
  }

  try {
    const token = header.slice(7);
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch (err) {
    res.status(401).json({
      type: '/errors/unauthorized',
      title: 'Token expired or invalid',
      status: 401
    });
  }
}

Rate limiting protects your API from abuse, ensures fair usage, and prevents cascading failures. Every production API needs it.

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1711036800

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0

// Express rate limiting with express-rate-limit
const rateLimit = require('express-rate-limit');

const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 100,                   // 100 requests per window
  standardHeaders: true,      // RateLimit-* headers
  legacyHeaders: false,
  message: {
    type: '/errors/rate-limit',
    title: 'Too Many Requests',
    status: 429,
    detail: 'Rate limit exceeded. Try again later.'
  }
});

app.use('/api/', apiLimiter);

// Tiered limits per plan
const premiumLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5000,
  keyGenerator: (req) => req.user?.apiKey
});

HATEOAS (Hypermedia As The Engine Of Application State) means the API response includes links that tell the client what actions are available next. The client never hard-codes URLs.

// GET /api/v1/orders/789
{
  "data": {
    "id": 789,
    "status": "pending",
    "total": 59.99
  },
  "links": {
    "self":    { "href": "/api/v1/orders/789" },
    "cancel":  { "href": "/api/v1/orders/789/cancel", "method": "POST" },
    "pay":     { "href": "/api/v1/orders/789/pay", "method": "POST" },
    "customer": { "href": "/api/v1/users/42" }
  }
}

// After payment — cancel link disappears
{
  "data": { "id": 789, "status": "paid", "total": 59.99 },
  "links": {
    "self":   { "href": "/api/v1/orders/789" },
    "refund": { "href": "/api/v1/orders/789/refund", "method": "POST" },
    "receipt": { "href": "/api/v1/orders/789/receipt" }
  }
}

# First response
HTTP/1.1 200 OK
Last-Modified: Thu, 15 Mar 2025 10:30:00 GMT

# Conditional request
GET /api/v1/products/42
If-Modified-Since: Thu, 15 Mar 2025 10:30:00 GMT

# 304 if unchanged, 200 with body if changed

// Express ETag and caching middleware
app.get('/api/v1/products/:id', async (req, res) => {
  const product = await db.findById(req.params.id);
  const etag = crypto
    .createHash('md5')
    .update(JSON.stringify(product))
    .digest('hex');

  res.set({
    'ETag': `"${etag}"`,
    'Cache-Control': 'public, max-age=300',
    'Vary': 'Accept, Authorization'
  });

  if (req.headers['if-none-match'] === `"${etag}"`) {
    return res.status(304).end();
  }
  res.json({ data: product });
});

openapi: 3.0.3
info:
  title: Products API
  version: 1.0.0
paths:
  /api/v1/products:
    get:
      summary: List products
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'

// Auto-generate Swagger in Express
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const specs = swaggerJsdoc({
  definition: {
    openapi: '3.0.3',
    info: { title: 'My API', version: '1.0.0' }
  },
  apis: ['./routes/*.js']  // JSDoc annotations
});

app.use('/docs', swaggerUi.serve,
  swaggerUi.setup(specs));

// server.js — app setup
const express = require('express');
const app = express();

app.use(express.json());
app.use(cors());

// Routes
app.use('/api/v1/users', require('./routes/users'));
app.use('/api/v1/products', require('./routes/products'));

// 404 handler
app.use((req, res) => {
  res.status(404).json({
    type: '/errors/not-found',
    title: 'Not Found',
    status: 404,
    detail: `No route matches ${req.method} ${req.path}`
  });
});

// Global error handler
app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  res.status(status).json({
    type: `/errors/${err.code || 'server-error'}`,
    title: err.title || 'Internal Server Error',
    status,
    detail: status === 500 ? 'Something went wrong' : err.message,
    ...(err.errors && { errors: err.errors })
  });
});

app.listen(3000);

// routes/users.js — full CRUD
const router = require('express').Router();
const { body, validationResult } = require('express-validator');

// List users (paginated, filtered, sorted)
router.get('/', async (req, res, next) => {
  try {
    const { page = 1, per_page = 25, sort = '-created_at' } = req.query;
    const { data, total } = await User.findAll({
      page, perPage: per_page, sort
    });
    res.json({
      data,
      meta: { totalCount: total, page: +page, perPage: +per_page }
    });
  } catch (err) { next(err); }
});

// Create user (with validation)
router.post('/',
  body('email').isEmail(),
  body('firstName').trim().notEmpty(),
  async (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(422).json({
        type: '/errors/validation',
        title: 'Validation Error',
        status: 422,
        errors: errors.array()
      });
    }
    try {
      const user = await User.create(req.body);
      res.status(201)
        .location(`/api/v1/users/${user.id}`)
        .json({ data: user });
    } catch (err) { next(err); }
  }
);