Skip to content
routebase

10 guides, 106 chapters

API Guides

Each guide starts with the methods, explains where each one earns its place, and ends with how you put it into practice. The ten build on each other in the order they are numbered. Every chapter still stands on its own, so you can read the one you need and follow the links from there.

Guide 01

API Design

The decisions you make before you write a line of OpenAPI, from resource shape and method semantics through errors, pagination, idempotency and rate limits, each one with what it costs. Eleven chapters.

  1. 01Resources and URLs
  2. 02Methods and Status Codes
  3. 03Designing API Errors
  4. 04Actions That Are Not CRUD
  5. 05Pagination, Filtering and Sorting
  6. 06Idempotency and Retries
  7. 07Rate Limits as a Design Decision
  8. 08Consistency Across an API
  9. 09Design for the Client You Now Have
  10. 10What to Look for in an API Design Tool
Start with the overview

Guide 02

OpenAPI

What an OpenAPI document is, how one is put together, how to write schemas that hold up, how to validate and lint it, and everything you can derive from the file once it exists. Eleven chapters.

  1. 01OpenAPI vs Swagger
  2. 02Anatomy of an OpenAPI Document
  3. 03OpenAPI 3.0, 3.1 and 3.2
  4. 04OpenAPI Schemas
  5. 05Parameters, Request Bodies and Responses
  6. 06Components and Reuse
  7. 07Validating and Linting OpenAPI
  8. 08From Collections to Contracts
  9. 09What You Derive From OpenAPI
  10. 10Descriptions an Agent Can Use
Start with the overview

Guide 03

API Mocking

What a mock server answers and what it never proves, how one is generated from a contract, how to make it behave like the network it replaces, and how to stop it drifting. Eleven chapters.

  1. 01Mocking an API from an OpenAPI Contract
  2. 02Which Rule Answers a Mock Request
  3. 03Mock Data Worth Testing Against
  4. 04One Endpoint, Many Answers
  5. 05Making the Mock Unpleasant on Purpose
  6. 06Stateful Mocks: When the Attempt Needs Memory
  7. 07Keeping Mocks in Sync With the Spec
  8. 08Mocks in the Frontend Workflow
  9. 09When Not to Mock
  10. 10What to Look For in an API Mocking Tool
Start with the overview

Guide 04

API Documentation

What belongs in API documentation, how to write it, how to keep it true while the API changes, and how to publish and measure it. Ten chapters from the page inventory through hosting.

  1. 01What Belongs in API Documentation
  2. 02How to Write API Reference Documentation
  3. 03Keeping API Documentation Up to Date
  4. 04Interactive API Documentation
  5. 05API Documentation for AI Agents
  6. 06Publishing and Hosting API Documentation
  7. 07API Docs as Code
  8. 08Measuring API Documentation
  9. 09API Documentation Structure and Navigation
  10. 10What to Look For in API Documentation Tools
Start with the overview

Guide 05

API Testing

The methods, the strategy that ties them together, and how to run each one in practice. Twelve chapters covering functional, contract, workflow, data-driven, performance, security and production testing.

  1. 01Types of API Testing, and Where Each One Fits
  2. 02Contract Testing vs. Integration Testing
  3. 03Functional API Tests: What to Assert
  4. 04API Integration Testing With Scenarios
  5. 05API Test Data and Data-Driven Runs
  6. 06API Testing Environments, Auth and Secrets
  7. 07API Performance Testing: Load, Stress and Soak
  8. 08API Security Testing
  9. 09Automated API Testing in CI/CD
  10. 10API Monitoring and Contract Drift in Production
  11. 11Testing an API With an AI Agent Over MCP
  12. 12What to Look For in API Testing Tools
Start with the overview

Guide 06

API Authentication

Every method worth knowing, from API keys and JWT through the OAuth 2.0 grants to mutual TLS, with the trade-offs of each and how to set them up. Eleven chapters, every security claim sourced to its RFC.

  1. 01API Keys: What They Are and What They Are Not
  2. 02HTTP Basic Authentication and Digest, Explained
  3. 03Bearer Tokens and JWT
  4. 04OAuth 2.0: The Grant Types, Explained
  5. 05OpenID Connect
  6. 06Request Signing: OAuth 1.0, AWS SigV4 and Hawk
  7. 07Mutual TLS, Cookies and Custom HMAC Schemes
  8. 08OpenAPI Security Schemes and Per-Endpoint Auth
  9. 09Setting Up API Authentication in Routebase, End to End
  10. 10API Authentication Testing: The Negative Cases
  11. 11Choosing an API Authentication Method
Start with the overview

Guide 07

API Security

The OWASP API Security Top 10 from 2023 as a working map, what each category looks like from the outside, how to scan a running API for them, and what no scanner will ever find. Thirteen chapters.

  1. 01Broken Object Level Authorization
  2. 02Function and Property Level Authorization
  3. 03Authentication Failures
  4. 04Unrestricted Resource Consumption
  5. 05Server Side Request Forgery
  6. 06Misconfiguration, TLS and Headers
  7. 07Shadow and Zombie APIs
  8. 08Running a Scan Against a Live API
  9. 09Triaging Findings
  10. 10API Security in CI/CD
  11. 11What a Scanner Cannot Find
  12. 12What to Look for in an API Security Testing Tool
Start with the overview

Guide 08

API Versioning

Every versioning method, what each one costs, when a new version is unavoidable, and when the right answer is not to version at all. Twelve chapters from breaking changes through deprecation and sunset.

  1. 01What Counts as a Breaking Change in an API
  2. 02API Versioning Strategies Compared
  3. 03Semantic Versioning for APIs
  4. 04When You Must Version an API
  5. 05When API Versioning Does Not Matter
  6. 06Backward Compatible API Changes
  7. 07Running Multiple API Versions at Once
  8. 08API Deprecation and the Sunset Header
  9. 09API Changelogs and Migration Guides
  10. 10OpenAPI Versioning
  11. 11Versioning Beyond REST: GraphQL, gRPC and Events
  12. 12Choosing an API Versioning Strategy
Start with the overview

Guide 09

API Monitoring

What to watch on a live API, which kinds of check answer which question, how to set thresholds and alerts people still read, and how to catch a response that is wrong while the status code stays green. Ten chapters.

  1. 01Types of API Monitoring Checks: Health, Synthetic, Contract and SLA
  2. 02API Uptime, Latency and SLAs: What to Measure and How to Read It
  3. 03API Alerting Without the Noise: Thresholds, Windows and Cooldowns
  4. 04API Incidents and Maintenance Windows
  5. 05Contract Drift: Monitoring Correctness, Not Just Availability
  6. 06Design-First API Monitoring: Monitors That Wait
  7. 07Authentication and Secrets for API Monitors
  8. 08Data Freshness: The Failure a Schema Check Cannot See
  9. 09What to Look For in an API Monitoring Tool
Start with the overview

Guide 10

API Governance

How a design decision keeps applying to every API your organisation ships, including the ones built next quarter by people who were not in the room. Eleven chapters.

  1. 01What Belongs in an API Style Guide
  2. 02From a Document to a Check
  3. 03Severity and Enforcement
  4. 04Rules of Your Own
  5. 05Reuse Beats Inspection
  6. 06Consistent Headers Across Every API
  7. 07Measuring API Quality
  8. 08Rolling Governance Out Without Stopping the Team
  9. 09Governing Change
  10. 10What to Look for in an API Governance Tool
Start with the overview

Ready to ship on it?

Routebase is live. Design your API once — docs, mocks, tests, and monitoring all follow from the same source.

Start freeRead the docs

14-day Pro trial — no credit card required.