Knowledge graph what I know, drawn as a map
This is my knowledge, gathered over the years and laid out in one place. It began as the board I kept while writing the book on REST, and it has taken on everything since: what the web is made of, how a model is shaped, how a message crosses a boundary, how a system is kept standing once people depend on it.
Three areas, one graph. The dashed edges are the point — each joins an idea in one area to the place it is put to work in another. Drag to pan, scroll to zoom, click any node to read what it is.
nodes 399
web and API design 256
engineering practice 103
production 40
bridges 66
The index The same graph, in reading order. Every entry selects itself in the map above, where its description and its bridges are shown.
API knowledge What the web is made of, and what an API owes the people who call it.
Universal definitions General definition of an API Types of API What a private API actually means Design approaches Code first API first Design first Foundations of an HTTP API What HTTP rests on The one who inspired it, Vannevar Bush The Rapid Selector The Memex Hyperlinks As We May Think The one who tried, Ted Nelson The one who set it free, Sir Tim Berners-Lee The one with a thesis, Roy Thomas Fielding Three standards: HTML, HTTP, URI The web The thesis The architecture of the web Network-based application architecture The network Arpanet and Cyclades TCP and UDP The OSI model System resilience Centralised, decentralised, distributed IP, DNS, packet switching Representational State Transfer The constraints The properties REST applied to URIs REST applied to HTTP Receiving an HTTP request Anatomy of an HTTP request HTTP verbs Request headers Anatomy of a URL URN, URL, URI, IRI REST, resource and IRI The Richardson maturity model Safe, idempotent, neither Which verb is which Idempotent is not the same as safe Retrying a write with an idempotency key Answering properly HTTP status codes The common ones The lesser-known ones Specification versus implementation Response headers Values in a generic format Widespread formats Protobuf JSON XML The versions of HTTP HTTP/1.1 and its connection limit HTTP/2 multiplexing HTTP/3 and QUIC Where head-of-line blocking moves Pushing instead of polling WebSockets Server-sent events and Mercure What is at stake in building an API Fields of application Building an API over an existing system Bimodal IT Business technology APIs at the heart of the economy APIs as accelerators of digital transformation Principles of hyper-connectivity Hypermedia as the means HATEOAS SOA versus WOA Event-driven APIs Webhooks Signing the payload Storing the signature to refuse a replay Retrying a failed delivery Buy off the shelf, or build bespoke The hypermedia representation of a resource Resource Description Framework Collection+JSON UBER HAL Siren Mason JSON-LD Hydra Activity Streams JSON:API The ecosystem of an API Types of actor Watching your API for a better experience What makes an API succeed inside an ecosystem Advice for building an API from scratch Designing your API Writing an API guideline Writing an infrastructure guideline Choosing partner APIs Living with heterogeneous languages Listing and prioritising the steps The essentials of design Prototyping and its limits Opening your API to its ecosystem Promoting your API Public changelogs Social media aimed at developers Publishing on external marketplaces Notifying clients waiting on a feature Coordinating the evolution of the API Delivery methods Big bang Rolling Blue / green Canary Feature flag Version management methods Semantic versioning Definition Good practice Constraints Evolution strategy Definition Good practice Constraints Taking care of developers Collecting consumer needs Offering SDKs and libraries Collecting consumer usage Offering user support Documenting your API WADL, OpenAPI, Hydra, OData, IDL, protobuf Publishing documentation for humans Running a developer portal Taking care of consumers Choosing or creating an ontology What is an ontology Private or public OWL Examples of ontologies Functional responsibility ESB, API gateway and API management Definitions and application What an API gateway does The BFF approach The SPARQL approach Mapping the organisation Distributing responsibility Orchestration or choreography Orchestrating services Choreographing services Holding state together with sagas API granularity Approaches to communication and synchronisation Finding the right granularity Surviving a failure with fine granularity Testing your API The test pyramid Managing the cost and effort ratio Distributing test execution The domains of testing Usability and UX testing Unit testing Integration testing Property testing Security testing Production testing Testing tools Postman and Newman SmartBear API management Tooling built into the language Securing your API Users and permissions Separating users, authorisation, clients and resources Permission models Good practice Authentication methods OIDC Authorization code flow with PKCE Grant flow with PKCE Reference tooling OAuth 2 Through a browser Between APIs Other methods worth knowing mTLS PAKE WebAuthn Multi-factor OTP Sharing the access token with JOSE JWT JWS JWE and JWK Key rotation and JWKS Where the client keeps the token Monitoring every layer of the application Watching health Watching communications Applying OWASP good practice SQL injection Cross-site scripting Cross-site request forgery Server-side request forgery CORS as a security boundary SAST, DAST, IAST Following a request with a correlation ID Deploying your API Continuous integration pipeline Continuous deployment pipeline Bare metal versus cloud Choosing a host Performance What counts as a slow response The web architecture and the platform layers Caching Application cache HTTP cache Expiration Validation Invalidation Stale responses stale-on-error stale-while-revalidate Load balancing Asynchrony Queues Messages: event, command, query Getting value from your API Commercial strategy Outside-in strategy Adopting the ecosystem principle Collaborating with partners Observe, measure, iterate, repeat Dealing with dependencies KPIs Commercial KPIs Operational KPIs Adoption KPIs Production experience Clusters, databases and perimeters: the parts that only matter once something is actually serving traffic.
Clusters and infrastructure Kubernetes Helm charts Terraform Multi-region deployment Vertical scaling Docker layer caching Scheduled jobs Cost optimisation Database operations Indexes and query plans Query optimisation N+1 queries Connection pooling Read replicas Replication Backups Disaster recovery Encryption at rest Sharding and partitioning Perimeter and tokens Cloudflare as a WAF Where the browser keeps a bearer token JWKS and signing-key rotation Observability in production OpenTelemetry Tempo with Loki Escalation to a dedicated SRE team Rollback by redeploy Postmortems Resilience tuning Per-target initial timeouts Exponential backoff Fixed-interval retry Redis as the buffer under load Memory leaks in long-running workers Transport choices JSON-RPC rather than gRPC WebSockets chosen for simplicity The web and API half of this map is also kept onMiro , where it was first drawn.