← Back to all products
$29
REST API Design Guide
RESTful API design patterns, versioning strategies, pagination, filtering, error handling, and OpenAPI specs.
PythonYAMLMarkdownJSON
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 SampleFile Structure 30 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
├── interactive.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-pytest-9.0.2.pyc
│ ├── test_error_envelope.cpython-312.pyc
│ ├── test_pagination.cpython-312-pytest-9.0.2.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 ...