APIs: The Complete Guide

01 What is an API?

API stands for Application Programming Interface. It is a contract that lets two pieces of software talk to each other without either one needing to know how the other is built internally.

Think of a restaurant. You (the client) don't walk into the kitchen and cook. You tell the waiter what you want from a menu, the kitchen (the server) prepares it, and the waiter brings back exactly what you ordered. The menu is the API: a defined list of things you can ask for, and the format you must ask in.

Why APIs matter

02 Anatomy of an API Request

Every HTTP API call has the same five ingredients. Learn these and every API becomes readable.

A real request, decoded

POST /v1/products?notify=true HTTP/1.1
Host: api.shop.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Accept: application/json

{
  "name": "Mechanical Keyboard",
  "price": 129.99,
  "tags": ["hardware", "input"]
}

And the response

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/products/1087

{
  "id": 1087,
  "name": "Mechanical Keyboard",
  "price": 129.99,
  "createdAt": "2025-01-14T09:22:31Z"
}

03 Types of APIs

APIs are classified in two useful ways: by architecture/protocol and by audience.

A. By architecture & protocol

B. By audience

04 HTTP Methods (Verbs)

REST maps actions onto standard HTTP methods. Using them correctly makes your API predictable.

*PATCH can be made idempotent depending on the operations used.

Less-common but useful methods

• HEAD — same as GET but returns only headers (check existence, size, or last-modified).
• OPTIONS — asks what methods a resource supports. Browsers use it for CORS preflight.
• TRACE — echoes the request back; almost never used, often disabled for security.
• CONNECT — establishes a tunnel (e.g. HTTPS through a proxy).

05 HTTP Status Codes

The three-digit number in every response tells the client what happened — without reading the body.

Returning errors consistently

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The 'price' field must be a positive number.",
    "field": "price",
    "requestId": "req_8f2a91c"
  }
}

06 Authentication & Authorization

Authentication = who are you? Authorization = what are you allowed to do?

Sending credentials

# API key (header)
X-API-Key: sk_live_9f8a7b6c5d

# Bearer token (JWT or OAuth access token)
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# HTTP Basic
Authorization: Basic dXNlcjpwYXNzd29yZA==

The OAuth 2.0 Authorization Code flow

JWT structure — three Base64 parts

header.payload.signature

# Decoded payload example
{
  "sub": "user_42",
  "scope": "read:books write:books",
  "iat": 1705312800,
  "exp": 1705316400
}

07 How to Build an API

Here is the end-to-end process, followed by two complete working examples.

The 7-step process

1. Define the use cases. What will clients actually need to do? List them as user stories.
2. Model the resources. Nouns become endpoints: /users, /orders, /orders/42/items.
3. Design the contract. Choose URLs, methods, request/response shapes, and error formats. Write it down (OpenAPI/Swagger).
4. Pick a stack. Node/Express, Python/FastAPI, Go/Fiber, Java/Spring, Ruby/Rails — any is fine.
5. Implement + validate. Parse and validate every input. Never trust the client.
6. Add cross-cutting concerns. Auth, rate limiting, logging, error handling, CORS, versioning.
7. Document, test, deploy, monitor. Automate tests, ship behind HTTPS, watch latency and error rates.

Example A — Node.js + Express

const express = require('express');
const app = express();

app.use(express.json());   // parse JSON bodies

// In-memory "database" for the demo
let books = [
  { id: 1, title: 'The Pragmatic Programmer', author: 'Hunt & Thomas' }
];
let nextId = 2;

// ---------- READ ALL ----------
app.get('/api/books', (req, res) => {
  res.json({ data: books, count: books.length });
});

// ---------- READ ONE ----------
app.get('/api/books/:id', (req, res) => {
  const book = books.find(b => b.id === Number(req.params.id));
  if (!book) {
    return res.status(404).json({ error: 'Book not found' });
  }
  res.json(book);
});

// ---------- CREATE ----------
app.post('/api/books', (req, res) => {
  const { title, author } = req.body;

  // Validation: never trust the client
  if (!title || typeof title !== 'string') {
    return res.status(400).json({ error: 'title is required' });
  }

  const book = { id: nextId++, title, author: author || 'Unknown' };
  books.push(book);
  res.status(201).json(book);
});

// ---------- UPDATE (partial) ----------
app.patch('/api/books/:id', (req, res) => {
  const book = books.find(b => b.id === Number(req.params.id));
  if (!book) return res.status(404).json({ error: 'Book not found' });

  Object.assign(book, req.body);
  res.json(book);
});

// ---------- DELETE ----------
app.delete('/api/books/:id', (req, res) => {
  const before = books.length;
  books = books.filter(b => b.id !== Number(req.params.id));
  if (books.length === before) {
    return res.status(404).json({ error: 'Book not found' });
  }
  res.status(204).send();
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

Example B — Python + FastAPI

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="Books API", version="1.0")


class BookIn(BaseModel):
    title: str
    author: str = "Unknown"


class Book(BookIn):
    id: int


books: list[Book] = [Book(id=1, title="Dune", author="Herbert")]


@app.get("/api/books")
def list_books():
    return {"data": books, "count": len(books)}


@app.get("/api/books/{book_id}")
def get_book(book_id: int):
    for b in books:
        if b.id == book_id:
            return b
    raise HTTPException(status_code=404, detail="Book not found")


@app.post("/api/books", status_code=201)
def create_book(payload: BookIn):
    new_id = max((b.id for b in books), default=0) + 1
    book = Book(id=new_id, **payload.model_dump())
    books.append(book)
    return book

# Run with:  uvicorn main:app --reload
# Free interactive docs at  http://localhost:8000/docs

08 Designing Clean Endpoints

✅ Do

• Use plural nouns for collections: /users, not /getUser.
• Use nesting for real ownership: /users/42/orders.
• Use query parameters for filtering, sorting, and pagination.
• Version your API from day one: /v1/... or a custom header.
• Return consistent envelopes for lists: { data: [...], meta: {...} }.
• Use kebab-case for multi-word paths: /order-items, not /orderItems.

❌ Don't

• Put verbs in the URL: /deleteUser/42 → use DELETE /users/42.
• Return 200 OK with an error message inside the body.
• Expose raw database IDs or internal table names.
• Break existing clients — add fields, don't rename or remove them without a new version.
• Nest more than two levels deep: /users/1/orders/2/items/3/reviews is a code smell.

Pagination, filtering, sorting

# Offset pagination (simple, good for small datasets)
GET /v1/products?page=3&limit=20

# Cursor pagination (stable & fast for large datasets)
GET /v1/products?limit=20&cursor=eyJpZCI6MTA4N30

# Filtering + sorting (minus = descending)
GET /v1/products?category=laptops&minPrice=500&sort=-createdAt

# Sparse fieldsets (return only what you need)
GET /v1/products?fields=id,name,price

{
  "data": [ /* 20 items */ ],
  "meta": {
    "page": 3,
    "limit": 20,
    "total": 412,
    "nextCursor": "eyJpZCI6MTEwN30"
  }
}

API Design Maturity — the Richardson Maturity Model

09 How to Connect to an API

Consuming an API follows the same loop in every language: build a request → send it → check the status → parse the body → handle errors.

JavaScript — fetch (built into browsers & Node 18+)

async function createBook() {
  const response = await fetch('https://api.example.com/v1/books', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.API_TOKEN}`
    },
    body: JSON.stringify({ title: 'Clean Code', author: 'Robert Martin' })
  });

  // fetch does NOT throw on 4xx/5xx — check manually
  if (!response.ok) {
    const detail = await response.text();
    throw new Error(`HTTP ${response.status}: ${detail}`);
  }

  return response.json();
}

JavaScript — axios (popular library)

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.example.com/v1',
  timeout: 10000,
  headers: { Authorization: `Bearer ${token}` }
});

try {
  const { data } = await api.get('/books', { params: { page: 1, limit: 20 } });
  console.log(data);
} catch (err) {
  if (err.response)  console.error('Server said:', err.response.status);
  else if (err.request) console.error('No response received');
  else                 console.error('Setup error:', err.message);
}

Python — requests

import requests

response = requests.post(
    "https://api.example.com/v1/books",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"title": "Clean Code", "author": "Robert Martin"},
    timeout=10,
)

response.raise_for_status()   # throws on 4xx/5xx
book = response.json()
print(book["id"])

cURL — the universal debugging tool

# GET with auth header
curl https://api.example.com/v1/books \
  -H "Authorization: Bearer $TOKEN"

# POST with a JSON body (-i shows response headers)
curl -i -X POST https://api.example.com/v1/books \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Clean Code","author":"Robert Martin"}'

GraphQL — one endpoint, exact fields

query {
  user(id: "42") {
    name
    email
    orders(last: 3) {
      id
      total
    }
  }
}

const res = await fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
  body: JSON.stringify({ query, variables: { id: '42' } })
});

Handling rate limits gracefully

// Respect 429 and the Retry-After header
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status !== 429 && res.status < 500) return res;

    const wait = Number(res.headers.get('Retry-After')) * 1000
               || 2 ** attempt * 500;   // exponential backoff

    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error('Max retries exceeded');
}

10 REST vs GraphQL vs SOAP vs gRPC

11 API Versioning

Every API changes. Versioning is how you evolve without breaking existing clients.

Four common strategies

Breaking vs non-breaking changes

Deprecation done right

Deprecation: Sat, 01 Mar 2025 00:00:00 GMT
Sunset: Tue, 01 Jul 2025 00:00:00 GMT
Link: <https://api.example.com/v2/books>; rel="successor-version"

• Announce the change in a changelog and email list months ahead.
• Log which clients still hit the old version so you can reach out.
• Run both versions in parallel for a deprecation window.
• Return the Sunset header so clients know the deadline programmatically.

12 API Security Deep Dive

APIs are a top attack target because they often expose business logic and data directly. Here is what to defend against.

OWASP API Security Top 10 (2023)

Rate-limiting algorithms

Standard rate-limit headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1705316400
Retry-After: 30

Essential security headers

Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Cache-Control: no-store   # for sensitive responses

13 Architecture Patterns

How APIs are arranged in real systems — the shapes you'll see in job interviews and production diagrams.

Typical layered request path

Microservice communication: sync vs async

14 Caching & Performance

Caching is the single highest-leverage way to make an API fast and cheap. HTTP has caching built in — use it.

Key caching headers

Conditional requests — saving bandwidth

# First request: server responds with an ETag
GET /v1/products/42
ETag: "33a64df5"

# Next request: client sends the ETag back
GET /v1/products/42
If-None-Match: "33a64df5"

# If unchanged, server replies with a tiny 304 and no body
HTTP/1.1 304 Not Modified

Cache-Control directives worth knowing

• public — any cache (including CDNs) may store it.
• private — only the end user's browser may cache it.
• no-store — never cache (use for sensitive data).
• no-cache — may store, but must revalidate before each use.
• max-age=600 — fresh for 600 seconds.
• stale-while-revalidate=60 — serve stale for 60s while refreshing in the background.

Other performance wins

15 Real-time APIs

Sometimes the server needs to tell the client something now, instead of waiting to be asked. Four main patterns exist.

WebSocket — minimal example

// Browser side
const ws = new WebSocket('wss://api.example.com/ws');

ws.addEventListener('open',    () => ws.send(JSON.stringify({ type: 'subscribe', room: 'prices' })));
ws.addEventListener('message', e => console.log('Update:', JSON.parse(e.data)));
ws.addEventListener('close',   () => console.log('Disconnected'));

Server-Sent Events — simpler, one-way

// Browser side
const es = new EventSource('/api/notifications/stream');

es.onmessage = e => console.log('Notification:', e.data);
es.onerror   = () => console.log('Stream lost, retrying…');

Webhook — the server calls you

// Express receiver for a Stripe-style webhook
app.post('/webhooks/payment', express.raw({ type: '*/*' }), (req, res) => {
  const signature = req.headers['stripe-signature'];

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body, signature, process.env.WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  if (event.type === 'payment_intent.succeeded') {
    // handle the event…
  }

  res.json({ received: true });   // respond fast
});

16 Documentation & Developer Experience

A great API with bad docs is a bad API. DX (developer experience) is a feature.

What a great doc page contains

• Authentication — how to get and use a key or token.
• Base URL and environments (sandbox vs production).
• Every endpoint with method, path, params, sample request, sample response.
• Error reference — every code and what it means.
• Rate limits — the numbers and the headers.
• Pagination — how it works and where to find the next page.
• Webhooks — events, payloads, signature verification.
• Changelog & deprecation policy.

OpenAPI snippet

openapi: 3.0.3
info:
  title: Books API
  version: 1.0.0
paths:
  /books:
    get:
      summary: List all books
      responses:
        '200':
          description: A list of books
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Book' }

17 Testing & Monitoring

Untested APIs break silently. Unmonitored APIs break loudly at 3 a.m.

Testing layers

Monitoring: the four golden signals

Observability: the three pillars

• Logs — structured JSON events with a request ID so you can trace a single call.
• Metrics — numeric time series for dashboards and alerting.
• Traces — a single request's journey across services (OpenTelemetry, Jaeger, Tempo).

SLI, SLO, SLA — what's the difference?

Distributed tracing — propag

# Trace context propagates via headers
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
X-Request-ID: req_8f2a91c

18 Best Practices Checklist

Security quick wins

• Least privilege: scopes and roles should grant the minimum needed.
• Short-lived tokens: access tokens expire in minutes; refresh tokens rotate.
• Never log secrets: redact Authorization headers from logs.
• Prevent injection: always use parameterized queries for the database.
• Limit payload size: cap request bodies to avoid memory exhaustion.
• Use a gateway: centralize auth, throttling, and TLS termination.

19 Tools & Ecosystem

Popular frameworks for building APIs

20 Technical Glossary

Core API vocabulary in plain language.

21 Acronyms & Idioms for Beginners

Every field has its own language. Here is the API world's — explained without jargon.

A. Acronyms you'll see everywhere

B. Idioms & phrases you'll hear on day one