← Back to all products
$29
REST API Design Guide
RESTful API design patterns, versioning strategies, pagination, filtering, error handling, and OpenAPI specs.
JSONMarkdownYAMLPython
📄 Product Preview
Try the interactive reader and demo tools below, or get the full product with all content unlocked.
📖 Interactive Reader (Free Preview) ⚙ Try Demo Tools 📦 Download Free Sample📁 File Structure 26 files
rest-api-design-guide/
├── LICENSE
├── README.md
├── examples/
│ ├── error-responses.json
│ ├── openapi.yaml
│ └── sample-requests.http
├── free-sample.zip
├── guide/
│ ├── error-handling.md
│ ├── idempotency-and-caching.md
│ ├── pagination-and-filtering.md
│ ├── rest-design-principles.md
│ └── versioning-strategies.md
├── guides/
│ ├── error-handling.md
│ ├── idempotency-and-caching.md
│ ├── pagination-and-filtering.md
│ ├── rest-design-principles.md
│ └── versioning-strategies.md
├── index.html
├── src/
│ ├── __pycache__/
│ │ ├── error_envelope.cpython-312.pyc
│ │ └── pagination.cpython-312.pyc
│ ├── error_envelope.py
│ ├── etag.py
│ └── pagination.py
└── tests/
├── __pycache__/
│ ├── test_error_envelope.cpython-312.pyc
│ └── test_pagination.cpython-312.pyc
├── test_error_envelope.py
└── test_pagination.py
📖 Documentation Preview README excerpt
RESTful API Design Guide
A comprehensive, battle-tested reference for designing robust REST APIs. Covers design principles, versioning strategies, pagination, filtering, error handling, idempotency, caching, and includes a complete OpenAPI 3.1 specification for a realistic Orders API -- plus runnable Python reference implementations you can drop into any project.
What's Inside
| Directory | Contents |
|---|---|
guides/ | Five deep-dive reference documents (~40 pages total) covering REST design end-to-end |
examples/ | Full OpenAPI 3.1 spec, HTTP request samples, error response catalog |
src/ | Runnable Python modules: pagination helpers, RFC 7807 error envelopes, ETag utilities |
tests/ | Unit tests for every src/ module (stdlib unittest -- no pip installs) |
Features
- REST Design Principles -- Resource naming, HTTP method semantics, HATEOAS, content negotiation, and the Richardson Maturity Model with concrete before/after examples.
- Versioning Strategies -- URI path, query param, header, and content-type versioning compared with migration playbooks.
- Pagination & Filtering -- Offset, cursor, keyset, and time-based pagination with Python implementations. Field filtering, sorting, full-text search patterns.
- Error Handling -- RFC 7807 Problem Details, error envelopes, retry-friendly status codes, and a complete error response catalog in JSON.
- Idempotency & Caching -- Idempotency keys, conditional requests (ETags, If-Match, If-None-Match), Cache-Control strategies, and stale-while-revalidate patterns.
- OpenAPI 3.1 Spec -- A complete, realistic Orders API specification with 12 endpoints, request/response schemas, error definitions, and security schemes.
Quick Start
Read the Guides
Start with the design principles, then read in order:
guides/rest-design-principles.md # Foundations
guides/versioning-strategies.md # How to evolve your API
guides/pagination-and-filtering.md # Handling large datasets
guides/error-handling.md # Consistent error responses
guides/idempotency-and-caching.md # Performance & reliability
Run the Python Modules
Every Python file runs standalone with a __main__ demo. No pip installs needed -- stdlib only.
# Pagination helpers -- see offset + cursor pagination in action
python3 src/pagination.py
# RFC 7807 error envelopes -- generate Problem Details JSON
python3 src/error_envelope.py
# ETag utilities -- generate and validate entity tags
python3 src/etag.py
Run the Tests
# Run all tests
python3 -m unittest discover -s tests -v
# Run a specific test module
python3 -m unittest tests.test_pagination -v
python3 -m unittest tests.test_error_envelope -v
*... continues with setup instructions, usage examples, and more.*
📄 Code Sample .py preview
src/error_envelope.py
"""RFC 7807 Problem Details error envelope builder.
Implements the RFC 7807 / RFC 9457 "Problem Details for HTTP APIs" standard.
Provides a ProblemDetail dataclass, a pre-built ErrorCatalog with common
HTTP errors, and helper functions for building consistent error responses.
Uses only the Python standard library -- no external dependencies.
References:
- RFC 7807: https://datatracker.ietf.org/doc/html/rfc7807
- RFC 9457: https://datatracker.ietf.org/doc/html/rfc9457 (supersedes 7807)
Example:
problem = ProblemDetail(
type_uri="validation-error",
title="Validation Error",
status=422,
detail="The 'email' field is not a valid email address.",
instance="/users",
)
print(problem.to_json(indent=2))
"""
from __future__ import annotations
import json
import logging
import uuid
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------
# Base URI for error type identifiers. The error slug is appended to this.
# Ideally, each URI resolves to documentation explaining the error.
DEFAULT_ERROR_TYPE_BASE_URI: str = "https://api.example.com/errors/"
# Content type for RFC 7807 responses
PROBLEM_JSON_CONTENT_TYPE: str = "application/problem+json"
# ---------------------------------------------------------------------------
# Field-level validation error
# ---------------------------------------------------------------------------
# ... 397 more lines ...