APIs You Won't Hate

Executive Summary: Building Web APIs That Stand the Test of Time

In modern enterprise architectures, APIs are the connective tissue linking single-page web applications, mobile devices, microservices, and third-party partner integrations. However, many engineering teams treat API development as an afterthought—slapping ad-hoc HTTP endpoints on database models without contract design, request validation, or versioning plans. Over time, these APIs degenerate into a tangled web of breaking changes, inconsistent error formats, security holes, and high maintenance overhead.

APIs You Won't Hate provides a clean, battle-tested engineering blueprint for building web APIs that developers love to consume and engineers take pride in maintaining. Spanning 140 high-density pages, this handbook teaches backend engineers, API architects, and full-stack developers how to adopt an API-First mindset, write strict OpenAPI 3.1 contracts, enforce JSON Schema validation, implement high-performance cursor pagination, and gracefully sunset legacy API versions.

Deep Dive: Core Pillars of Modern API Architecture

The handbook breaks modern API design down into five practical, production-ready domains:

1. API-First Development & OpenAPI v3.1 Specification

Instead of writing backend code first and generating messy documentation later, the book advocates for API-First design. Teams draft their OpenAPI 3.1 YAML specifications first:

• Contract Validation: Validating frontend and backend implementations against the shared OpenAPI contract during CI/CD builds.
• Automated Mock Servers: Enabling frontend developers to start building UI features immediately using Prism mock servers before backend code is written.

2. JSON Schema Validation & RFC 7807 Problem Details

Inconsistent error messages frustrate API clients. The handbook details how to standardize error reporting using the RFC 7807 Problem Details for HTTP APIs specification:

• Preventing Mass Assignment: Using strict JSON Schema input validation to reject unexpected payload fields (e.g. preventing users from submitting "is_admin": true).
• Standardized Errors: Returning application/problem+json content types with clear type, title, status, detail, and invalid_params objects.

3. Cursor-Based Pagination vs. Offset Pagination

Offset pagination (OFFSET 100000) causes severe database performance degradation on large datasets. The book illustrates how to implement opaque Cursor Pagination (Keyset Pagination):

• Constant O(1) Performance: Querying database records using indexed timestamp or ID filters (WHERE id > cursor_id ORDER BY id ASC LIMIT 20).
• Preventing Page Drift: Ensuring users don't see duplicate or skipped items when new records are inserted while paginating.

Field Engineering: OpenAPI v3.1 Spec & Middleware Snippets

Chapter 5 of the handbook contains practical code snippets for API spec definitions and Express middleware enforcement:

openapi: 3.1.0
info:
  title: Money Mitra Network Payment API
  version: 1.2.0
paths:
  /v1/payments:
    post:
      summary: Create Payment Intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency, customer_id]
              properties:
                amount: { type: integer, minimum: 100 }
                currency: { type: string, enum: [INR, USD, EUR] }
                customer_id: { type: string, format: uuid }
      responses:
        '201':
          description: Payment Created Successfully
        '422':
          description: Unprocessable Entity (Validation Error)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        invalid_params:
          type: array
          items:
            properties:
              name: { type: string }
              reason: { type: string }

const express = require('express');
const router = express.Router();

router.get('/v1/transactions', async (req, res) => {
    const limit = parseInt(req.query.limit) || 20;
    const rawCursor = req.query.cursor;
    let decodedId = 0;

    if (rawCursor) {
        // Decode Base64 Cursor ID
        decodedId = parseInt(Buffer.from(rawCursor, 'base64').toString('ascii'));
    }

    // High-Performance Keyset Database Query
    const query = `
        SELECT id, amount, currency, created_at 
        FROM transactions 
        WHERE id > $1 
        ORDER BY id ASC 
        LIMIT $2
    `;
    const results = await db.query(query, [decodedId, limit + 1]);

    const hasMore = results.length > limit;
    const items = hasMore ? results.slice(0, limit) : results;
    const nextCursor = hasMore ? Buffer.from(items[items.length - 1].id.toString()).toString('base64') : null;

    res.json({
        data: items,
        pagination: {
            has_more: hasMore,
            next_cursor: nextCursor
        }
    });
});

Complete Table of Contents & Module Syllabus

• Module 01 API-First Architecture & Design Philosophy

  Pages 1–18
  Introduction to API-First engineering, REST vs GraphQL vs gRPC, overcoming API sprawl, and establishing team-wide API style guides.
• Module 02 Resource Modeling, REST Semantics & OpenAPI 3.1

  Pages 19–36
  Nouns over verbs URI modeling, HTTP status code semantics, drafting OpenAPI 3.1 YAML contracts, and Prism mock server automation.
• Module 03 Data Validation, JSON Schema & RFC 7807 Error Design

  Pages 37–54
  JSON Schema validation, preventing mass-assignment vulnerabilities, RFC 7807 Problem Details error responses, and payload sanitization.
• Module 04 High-Performance Pagination, Filtering & Sorting

  Pages 55–72
  Offset vs Cursor (Keyset) pagination, building scalable filtering parameters, sorting syntax, and database query optimization.
• Module 05 API Security: OAuth 2.0, JWT Tokens & Rate Limiting

  Pages 73–90
  OAuth 2.0 grant types, JWT validation best practices, API key scoping, sliding window rate limiting algorithms, and OWASP API Top 10 mitigations.
• Module 06 GraphQL vs REST: Schema Design & N+1 Query Optimization

  Pages 91–108
  GraphQL schema design, query complexity analysis, solving the N+1 database problem with DataLoader, and rate-limiting GraphQL queries.
• Module 07 API Versioning, Deprecation & Sunset Header Strategies

  Pages 109–124
  URL path vs Header versioning, managing non-breaking vs breaking changes, implementing the `Sunset` HTTP header, and graceful deprecation timelines.
• Module 08 API Testing, Contract Testing & Gateway Deployment

  Pages 125–140
  Consumer-driven contract testing with Pact, automated API integration tests, Kong / Cloudflare API Gateway deployment, and continuous documentation pipelines.

Who Should Read This Handbook?

This handbook is designed for software developers and architects responsible for web services:

Verified API Architect Reviews

Frequently Asked Questions