# Guides — Routebase

> Long-form guides on API testing, API authentication, API versioning, API documentation, OpenAPI, API monitoring, API design, API mocking, API governance and API security, covering the methods, the trade-offs between them, and how to put them into practice.

Canonical page: https://routebase.dev/guides/

## [API Design](https://routebase.dev/guides/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. [Resources and URLs](https://routebase.dev/guides/api-design/resources-and-urls/): How to pick the things your API exposes, why nesting stops paying after one level, what a path convention is worth, and which identifiers are safe to put in a URL.
2. [Methods and Status Codes](https://routebase.dev/guides/api-design/http-methods-and-status-codes/): What each HTTP method promises a caller, why PUT and PATCH are not interchangeable, and which status code sets which expectation, with the RFC behind each one.
3. [Designing API Errors](https://routebase.dev/guides/api-design/designing-api-errors/): One shape for every failure, why an error code is a contract and a message is not, what belongs in a problem document, and what has to stay out of it.
4. [Actions That Are Not CRUD](https://routebase.dev/guides/api-design/actions-that-are-not-crud/): Cancel, publish, retry, search and bulk edit, modelled three different ways, with what each modelling costs and the questions that decide between them.
5. [Pagination, Filtering and Sorting](https://routebase.dev/guides/api-design/api-pagination-filtering-and-sorting/): Offset against cursor and what each costs when the data changes underneath, why limits are not optional, and how much of the filter and sort syntax is actually standardised.
6. [Idempotency and Retries](https://routebase.dev/guides/api-design/idempotency-and-retries/): Why a timeout is ambiguous, what an idempotency key actually promises, how long a stored result has to live, and which parts of the pattern are standardised.
7. [Rate Limits as a Design Decision](https://routebase.dev/guides/api-design/api-rate-limiting/): What a published limit promises a caller, why 429 needs Retry-After, how little of the header convention is standardised, and what a limit should be counted against.
8. [Consistency Across an API](https://routebase.dev/guides/api-design/consistency-across-an-api/): Why the same decision has to appear at every endpoint, why intention is not a mechanism, and the three things that actually hold a convention in place over time.
9. [Design for the Client You Now Have](https://routebase.dev/guides/api-design/designing-for-agent-clients/): Hypermedia promised runtime discovery to clients that were all generated ahead of time. A caller that reads your description at runtime finally exists, and it reads the prose.
10. [What to Look for in an API Design Tool](https://routebase.dev/guides/api-design/api-design-tools/): Eight criteria that decide whether a design tool still helps in a year, written as questions to ask rather than as a list of vendors.

## [OpenAPI](https://routebase.dev/guides/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. [OpenAPI vs Swagger](https://routebase.dev/guides/openapi/openapi-vs-swagger/): Where the two names come from, what changed when Swagger 2.0 became OpenAPI 3.0, which tools still carry the Swagger name, and which file your tooling actually expects.
2. [Anatomy of an OpenAPI Document](https://routebase.dev/guides/openapi/anatomy-of-an-openapi-document/): Every top-level field of an OpenAPI document explained in the order you meet it, with one complete working example and the difference between YAML and JSON.
3. [OpenAPI 3.0, 3.1 and 3.2](https://routebase.dev/guides/openapi/openapi-3-0-3-1-3-2/): What changed when 3.1 adopted JSON Schema 2020-12, what 3.2 added on top, and what a document and its tooling actually have to touch on the way up.
4. [OpenAPI Schemas](https://routebase.dev/guides/openapi/openapi-schemas/): Objects, arrays and primitives, the difference between allOf, oneOf and anyOf, enums that carry meaning, formats, nullability in both dialects, and examples that stay true.
5. [Parameters, Request Bodies and Responses](https://routebase.dev/guides/openapi/openapi-parameters-request-bodies-and-responses/): The four parameter locations and what each one is for, how a request body is described, responses per status code with headers and examples, and the errors most documents leave out.
6. [Components and Reuse](https://routebase.dev/guides/openapi/openapi-components-and-reuse/): What lives under components, how a reference works, when extracting something is worth it and when it is premature, and what changes once a definition is shared across teams.
7. [Validating and Linting OpenAPI](https://routebase.dev/guides/openapi/validating-and-linting-openapi/): Validation answers whether a document is legal OpenAPI and linting answers whether it is any good. What each one catches, which rules find real defects, and how severities decide what blocks a release.
8. [From Collections to Contracts](https://routebase.dev/guides/openapi/importing-postman-and-insomnia-collections/): Why a Postman or Insomnia collection is not an API contract, what an importer can infer from example data and what it cannot, and the work that is left after the import finishes.
9. [What You Derive From OpenAPI](https://routebase.dev/guides/openapi/what-you-derive-from-openapi/): Reference documentation, mock servers, contract tests, monitors and code samples all come out of the same document. What each one needs from it, and where generation stops being useful.
10. [Descriptions an Agent Can Use](https://routebase.dev/guides/openapi/openapi-descriptions-for-agents/): What a coding agent reads out of an OpenAPI document, the four questions a description has to answer, and why the fields people treat as decoration are the ones that decide whether the call succeeds.

## [API Mocking](https://routebase.dev/guides/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. [Mocking an API from an OpenAPI Contract](https://routebase.dev/guides/api-mocking/mock-api-from-openapi/): Why mocks are derived rather than written, what a generator can read out of paths, status codes and schemas, what it cannot know, and why coverage is the measure that matters.
2. [Which Rule Answers a Mock Request](https://routebase.dev/guides/api-mocking/mock-request-matching/): A mock server is a router before it is anything else. What can be matched, why several rules routinely overlap, how priority breaks the tie, and what should happen when nothing matches.
3. [Mock Data Worth Testing Against](https://routebase.dev/guides/api-mocking/mock-data-generation/): Static, generated and fixture data as three sources with three different failure modes, why a field filled with the word string ruins every layout, and how locale and time format quietly break a client.
4. [One Endpoint, Many Answers](https://routebase.dev/guides/api-mocking/conditional-mock-responses/): How to get a valid case, a not-found and a validation failure out of one route without a rule per outcome, what to branch on, and which fallback belongs at the end.
5. [Making the Mock Unpleasant on Purpose](https://routebase.dev/guides/api-mocking/simulating-errors-latency-and-rate-limits/): Latency with a range, failures at a probability, a dead socket rather than a clean 500, and the 429 nobody handles. The four conditions a client only meets in production unless the mock produces them.
6. [Stateful Mocks: When the Attempt Needs Memory](https://routebase.dev/guides/api-mocking/stateful-mocks/): Why a create followed by a list is the flow every stateless mock fails, what state buys you in a cart or a wizard, and where memory turns a mock into a bad backend.
7. [Keeping Mocks in Sync With the Spec](https://routebase.dev/guides/api-mocking/keeping-mocks-in-sync/): A mock behind the contract is worse than no mock. The three states a generated rule can be in, why a published version should freeze rather than follow, and what regeneration overwrites.
8. [Mocks in the Frontend Workflow](https://routebase.dev/guides/api-mocking/mocking-for-frontend-development/): Starting on day one instead of waiting, the base URL as configuration rather than a code branch, CORS and tokens in a browser, and what changes on the day you switch to the real backend.
9. [When Not to Mock](https://routebase.dev/guides/api-mocking/when-not-to-mock/): A passing run against a mock is a statement about the mock. The four questions mocking cannot answer, what takes over in each of them, and proxy mode as the path between a stand-in and the real service.
10. [What to Look For in an API Mocking Tool](https://routebase.dev/guides/api-mocking/api-mocking-tools/): Eight criteria that decide whether a mock is still trusted in three months, written as questions to ask rather than as a list of vendors, plus two exercises that settle it faster.

## [API Documentation](https://routebase.dev/guides/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. [What Belongs in API Documentation](https://routebase.dev/guides/api-documentation/what-belongs-in-api-documentation/): The pages nearly every API needs beyond the endpoint reference, what each one has to deliver, and how to tell a page that is doing its job from one that only looks complete.
2. [How to Write API Reference Documentation](https://routebase.dev/guides/api-documentation/how-to-write-api-documentation/): Summaries against descriptions, the questions a description has to answer, examples per response, enum values with meaning, and errors a reader can act on.
3. [Keeping API Documentation Up to Date](https://routebase.dev/guides/api-documentation/keeping-api-documentation-up-to-date/): Why documentation drifts away from the API, what to generate and what to write, how pinned snapshots and documentation versions work, and where a changelog comes from.
4. [Interactive API Documentation](https://routebase.dev/guides/api-documentation/interactive-api-documentation/): What a try-it playground has to do to be useful, which servers and credentials it may carry, how code samples earn their place, and what must never reach a documentation page.
5. [API Documentation for AI Agents](https://routebase.dev/guides/api-documentation/api-documentation-for-ai-agents/): What an agent can actually read from a documentation site, the llms.txt proposal, Markdown versions of pages, and why a generated endpoint page has to be readable as text.
6. [Publishing and Hosting API Documentation](https://routebase.dev/guides/api-documentation/publishing-and-hosting-api-documentation/): Where documentation lives, subdomain against your own domain, who is allowed to read it, how to take a version back, and the settings that decide how the site is found.
7. [API Docs as Code](https://routebase.dev/guides/api-documentation/api-docs-as-code/): Markdown in the repository against an editor in the portal, what each arrangement buys, what keeping both in step actually costs, and where the contract itself should live.
8. [Measuring API Documentation](https://routebase.dev/guides/api-documentation/measuring-api-documentation/): The signals that tell you whether documentation is working, why failed searches are the best backlog you have, how to read reader feedback, and which numbers to ignore.
9. [API Documentation Structure and Navigation](https://routebase.dev/guides/api-documentation/api-documentation-structure-and-navigation/): Trees against flat lists, how readers actually find a page, what a version switcher has to do, and branding that supports the content instead of competing with it.
10. [What to Look For in API Documentation Tools](https://routebase.dev/guides/api-documentation/api-documentation-tools/): Nine criteria that decide whether a documentation tool still fits in two years, written as questions to ask rather than as a list of vendors.

## [API Testing](https://routebase.dev/guides/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. [Types of API Testing, and Where Each One Fits](https://routebase.dev/guides/api-testing/types-of-api-testing/): Functional, contract, workflow, data-driven, performance, security and production tests, with what each one finds, what it misses, and where it belongs.
2. [Contract Testing vs. Integration Testing](https://routebase.dev/guides/api-testing/contract-testing-vs-integration-testing/): What a contract test proves, what an integration test proves, why neither replaces the other, and how drift opens up between a spec and the running service.
3. [Functional API Tests: What to Assert](https://routebase.dev/guides/api-testing/functional-api-tests/): How to choose assertions that catch real breakage without turning every unrelated change into a red run, plus negative cases, extraction and chaining.
4. [API Integration Testing With Scenarios](https://routebase.dev/guides/api-testing/api-integration-testing/): Testing multi-step flows where each call depends on the last, covering state between steps, asynchronous work, conditional branches and idempotency.
5. [API Test Data and Data-Driven Runs](https://routebase.dev/guides/api-testing/api-test-data/): How to make API tests deterministic, which means owning the data each run needs, cleaning up after it, and repeating one suite across many input rows.
6. [API Testing Environments, Auth and Secrets](https://routebase.dev/guides/api-testing/api-testing-environments/): Run one suite against development, staging and production without editing it, guard the environments nobody may write to, and keep credentials out of tests.
7. [API Performance Testing: Load, Stress and Soak](https://routebase.dev/guides/api-testing/api-performance-testing/): Load, stress and soak profiles, why the p95 beats the average, how to turn a latency budget into a pass or fail, and where a load test must never point.
8. [API Security Testing](https://routebase.dev/guides/api-testing/api-security-testing/): The OWASP API Security Top 10 from 2023 as a working map, authorization testing with two identities, fuzzing, and where automated scanning stops.
9. [Automated API Testing in CI/CD](https://routebase.dev/guides/api-testing/automated-api-testing-in-ci-cd/): Where the gate belongs, why exit codes are a contract, how to make a failure readable in the pipeline, and how to fix flakiness before people learn to rerun.
10. [API Monitoring and Contract Drift in Production](https://routebase.dev/guides/api-testing/api-monitoring-and-contract-drift/): Synthetic checks, contract validation on live responses, field freshness, and alert policies that people do not learn to ignore.
11. [Testing an API With an AI Agent Over MCP](https://routebase.dev/guides/api-testing/testing-with-an-agent-over-mcp/): What an agent can reliably derive from a specification, what it must not decide on its own, and why the permission model matters more than the model does.
12. [What to Look For in API Testing Tools](https://routebase.dev/guides/api-testing/api-testing-tools/): Nine criteria that decide whether a testing tool still fits in two years, written as questions to ask rather than as a list of vendors.

## [API Authentication](https://routebase.dev/guides/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. [API Keys: What They Are and What They Are Not](https://routebase.dev/guides/api-authentication/api-keys/): How an API key differs from a user credential, why the query string is the wrong place for one, and what scoping, rotation and per-key rate limits buy you.
2. [HTTP Basic Authentication and Digest, Explained](https://routebase.dev/guides/api-authentication/http-basic-authentication/): Why Base64 is not encryption, what Digest was designed to solve, where both still make sense, and the challenge-response mechanics behind them.
3. [Bearer Tokens and JWT](https://routebase.dev/guides/api-authentication/bearer-tokens-and-jwt/): Opaque tokens against self-contained ones, what a JWT actually guarantees, the validation mistakes that keep recurring, and what RFC 8725 says about them.
4. [OAuth 2.0: The Grant Types, Explained](https://routebase.dev/guides/api-authentication/oauth-2-grant-types/): The four roles, the grants that matter today, why PKCE is now required for every authorization code flow, and what RFC 9700 has retired.
5. [OpenID Connect](https://routebase.dev/guides/api-authentication/openid-connect/): The identity layer on top of OAuth 2.0, why an ID token is not an access token, what discovery buys you, and when plain OAuth is the right answer instead.
6. [Request Signing: OAuth 1.0, AWS SigV4 and Hawk](https://routebase.dev/guides/api-authentication/request-signing/): What request signing buys you over a bearer token, how nonces and timestamps stop replay, and where each of these four schemes still turns up.
7. [Mutual TLS, Cookies and Custom HMAC Schemes](https://routebase.dev/guides/api-authentication/mutual-tls-cookies-and-custom-hmac/): Certificates as identity at the transport layer, cookies and CSRF, and why a home-grown signing scheme is usually a worse version of one that already exists.
8. [OpenAPI Security Schemes and Per-Endpoint Auth](https://routebase.dev/guides/api-authentication/openapi-security-schemes/): Security schemes, per-operation requirements, scopes, and what consumers and agents can only learn from a specification that documents its authentication.
9. [Setting Up API Authentication in Routebase, End to End](https://routebase.dev/guides/api-authentication/setting-up-authentication-in-routebase/): Configure credentials once per environment, inherit them everywhere, keep secrets in variables, and cover the pipeline, scans and agents from one setup.
10. [API Authentication Testing: The Negative Cases](https://routebase.dev/guides/api-authentication/api-authentication-testing/): The negative cases worth writing, why 401 and 403 mean different things, and how two identities prove what a single-user suite structurally cannot.
11. [Choosing an API Authentication Method](https://routebase.dev/guides/api-authentication/choosing-an-api-authentication-method/): A decision table across complexity, revocation, rotation, delegation, browser exposure and maturity, plus the four questions that usually settle it first.

## [API Security](https://routebase.dev/guides/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. [Broken Object Level Authorization](https://routebase.dev/guides/api-security/broken-object-level-authorization/): API1:2023 is the flaw a single-user test suite cannot see, why proving it takes two identities from two tenants, and why 404 beats 403 on an object that is not yours.
2. [Function and Property Level Authorization](https://routebase.dev/guides/api-security/function-and-property-level-authorization/): API5:2023 and API3:2023, meaning the admin endpoint that forgot its role check and the response or request body that carries fields this caller has no business with.
3. [Authentication Failures](https://routebase.dev/guides/api-security/api-authentication-failures/): API2:2023 covers what breaks after the method is chosen correctly, from tokens accepted without a valid signature to a login endpoint that answers a thousand guesses.
4. [Unrestricted Resource Consumption](https://routebase.dev/guides/api-security/unrestricted-resource-consumption/): API4:2023 is a design failure rather than an operations problem, covering unbounded pages, oversized bodies, missing limits and the operations that cost money per call.
5. [Server Side Request Forgery](https://routebase.dev/guides/api-security/server-side-request-forgery/): API7:2023 turns any URL field in a request body into an instruction your server carries out, which is why the defence is an allow list rather than a filter.
6. [Misconfiguration, TLS and Headers](https://routebase.dev/guides/api-security/api-security-misconfiguration/): API8:2023 covers the settings that give ground away before anyone attacks anything, from cleartext transport and deprecated TLS versions to a wildcard CORS policy and a live debug endpoint.
7. [Shadow and Zombie APIs](https://routebase.dev/guides/api-security/shadow-and-zombie-apis/): API9:2023 is about what is still answering that nobody remembers deploying, from an old version left running to a staging host with production data behind it.
8. [Running a Scan Against a Live API](https://routebase.dev/guides/api-security/running-an-api-security-scan/): What a scan needs before it starts, what it does to the system it is pointed at, and why concurrency, delay and a time budget are courtesy settings rather than performance settings.
9. [Triaging Findings](https://routebase.dev/guides/api-security/triaging-security-findings/): Severity against confidence, reproducing before reporting, the difference between a false positive and an accepted risk, and what a security score is actually good for.
10. [API Security in CI/CD](https://routebase.dev/guides/api-security/api-security-in-ci-cd/): Where a scan belongs in a pipeline, how to set a gate that is still switched on in month three, and why findings belong in the code host rather than in a second tool.
11. [What a Scanner Cannot Find](https://routebase.dev/guides/api-security/what-a-scanner-cannot-find/): Business logic abuse, multi-step sequences and the APIs you consume are outside automated reach, and knowing where the line runs is what makes a green report mean anything.
12. [What to Look for in an API Security Testing Tool](https://routebase.dev/guides/api-security/api-security-testing-tools/): Eight criteria that decide whether a scanner is still being read in month three, written as questions to put to any tool including the one you already run.

## [API Versioning](https://routebase.dev/guides/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. [What Counts as a Breaking Change in an API](https://routebase.dev/guides/api-versioning/api-breaking-changes/): The changes that break a live consumer, the ones that only feel dangerous, the asymmetry between request and response, and how to classify them automatically.
2. [API Versioning Strategies Compared](https://routebase.dev/guides/api-versioning/api-versioning-strategies/): URL path, header, query parameter, media type and date-based versioning, with the routing, caching, tooling and visibility trade-offs of each.
3. [Semantic Versioning for APIs](https://routebase.dev/guides/api-versioning/semantic-versioning-for-apis/): How SemVer maps onto an HTTP API, why consumers only ever feel the major, what an alias like v1 really is, and where date-based numbering fits instead.
4. [When You Must Version an API](https://routebase.dev/guides/api-versioning/when-to-version-an-api/): The changes that have no additive path, the consumer situations that leave you no choice, and the semantic breaks that never show up in a diff.
5. [When API Versioning Does Not Matter](https://routebase.dev/guides/api-versioning/when-not-to-version-an-api/): The situations where a version number buys nothing, what running parallel versions really costs, and the alternatives that solve the same problem for less.
6. [Backward Compatible API Changes](https://routebase.dev/guides/api-versioning/backward-compatible-api-changes/): Additive evolution, the tolerant reader pattern, expand and contract, and how to prove an API stayed compatible instead of assuming it did.
7. [Running Multiple API Versions at Once](https://routebase.dev/guides/api-versioning/running-multiple-api-versions/): What it means for a version to be live in an environment, how routing decides who gets which one, and how docs, mocks and tests stay bound to it.
8. [API Deprecation and the Sunset Header](https://routebase.dev/guides/api-versioning/api-deprecation-and-sunset/): How to retire an endpoint or a version without ambushing anyone, using the Deprecation and Sunset headers, dated phases and a usable migration guide.
9. [API Changelogs and Migration Guides](https://routebase.dev/guides/api-versioning/api-changelogs-and-migration-guides/): What belongs in a changelog entry, how release notes differ from it, and how to write a migration guide that reaches the consumer at the moment they need it.
10. [OpenAPI Versioning](https://routebase.dev/guides/api-versioning/openapi-versioning/): The three different versions an OpenAPI document carries, how spec versions relate to the API consumers call, and where documentation versions fit.
11. [Versioning Beyond REST: GraphQL, gRPC and Events](https://routebase.dev/guides/api-versioning/versioning-graphql-grpc-and-events/): Why GraphQL evolves instead of versioning, how Protobuf field numbers make compatibility mechanical, and what a schema registry does for event streams.
12. [Choosing an API Versioning Strategy](https://routebase.dev/guides/api-versioning/choosing-an-api-versioning-strategy/): One decision path from the change in front of you to the method, with the criteria that actually separate the options and the policy each one needs.

## [API Monitoring](https://routebase.dev/guides/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. [Types of API Monitoring Checks: Health, Synthetic, Contract and SLA](https://routebase.dev/guides/api-monitoring/types-of-api-monitoring-checks/): What a health check proves, what a synthetic call adds, what contract validation catches that neither does, and how to pick intervals and timeouts that are worth their traffic.
2. [API Uptime, Latency and SLAs: What to Measure and How to Read It](https://routebase.dev/guides/api-monitoring/api-uptime-latency-and-slas/): Why the average response time hides the problem, what each additional nine actually costs in minutes, and how to keep an uptime figure honest enough to publish.
3. [API Alerting Without the Noise: Thresholds, Windows and Cooldowns](https://routebase.dev/guides/api-monitoring/api-alerting-and-alert-fatigue/): How to turn check results into alerts people still read, using sustained conditions, windows, cooldowns and a routing rule that keeps the paging set small.
4. [API Incidents and Maintenance Windows](https://routebase.dev/guides/api-monitoring/incidents-and-maintenance-windows/): When a run of failed checks should become a tracked incident, what acknowledging is supposed to mean, and how to schedule planned work without teaching anyone to ignore the channel.
5. [Contract Drift: Monitoring Correctness, Not Just Availability](https://routebase.dev/guides/api-monitoring/api-contract-drift/): Why a 200 proves nothing about the body behind it, which contract a live response should be validated against, and how a silent deviation becomes a record with an owner.
6. [Design-First API Monitoring: Monitors That Wait](https://routebase.dev/guides/api-monitoring/design-first-api-monitoring/): What changes when the contract exists before the service, why an unshipped endpoint must not report zero percent uptime, and what coverage does and does not tell you.
7. [Authentication and Secrets for API Monitors](https://routebase.dev/guides/api-monitoring/authentication-for-api-monitors/): Why an unauthenticated check watches the wrong surface, how to give a monitor an identity that expires gracefully, and why an expired token must not look like an outage.
8. [Data Freshness: The Failure a Schema Check Cannot See](https://routebase.dev/guides/api-monitoring/api-data-freshness-monitoring/): A field that keeps its shape and stops changing its value passes every validation perfectly, which is why staleness needs its own kind of check and its own kind of judgement.
9. [What to Look For in an API Monitoring Tool](https://routebase.dev/guides/api-monitoring/api-monitoring-tools/): Nine criteria that decide whether a monitoring setup is still trusted in a year, written as questions to ask rather than as a list of vendors.

## [API Governance](https://routebase.dev/guides/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. [What Belongs in an API Style Guide](https://routebase.dev/guides/api-governance/api-style-guide/): The subjects a style guide has to cover, the difference between a decision and a preference, and how to write rules that apply to an API you already shipped.
2. [From a Document to a Check](https://routebase.dev/guides/api-governance/machine-checkable-api-rules/): What an automated check can see in an API description, what it will never see, and what a design review is for once the machine has taken the mechanical half.
3. [Severity and Enforcement](https://routebase.dev/guides/api-governance/api-rule-severity-and-enforcement/): Error, warning and info as three different promises to the people who hit them, where a block is fair, and why an escape hatch is what keeps a guide switched on.
4. [Rules of Your Own](https://routebase.dev/guides/api-governance/custom-api-rules/): When a house convention earns an automated check, what a condition-based rule can express, and how to write one that does not fire on half your endpoints.
5. [Reuse Beats Inspection](https://routebase.dev/guides/api-governance/reuse-beats-inspection/): Why a shared definition removes a class of violation instead of reporting it, what belongs in an organisation-wide library, and how to distribute a change without breaking twelve services.
6. [Consistent Headers Across Every API](https://routebase.dev/guides/api-governance/consistent-api-headers/): Headers are the first place consistency decays. The four families worth standardising, why a policy beats a rule here, and what a policy in a contract does not do.
7. [Measuring API Quality](https://routebase.dev/guides/api-governance/measuring-api-quality/): What a weighted quality score is made of, why coverage is not quality, what the number cannot see, and what happens to it the moment a team is measured by it.
8. [Rolling Governance Out Without Stopping the Team](https://routebase.dev/guides/api-governance/rolling-out-api-governance/): The order that works is measure, then warn, then block. Why the reverse order gets governance switched off, how to treat existing APIs differently from new ones, and who grants an exception.
9. [Governing Change](https://routebase.dev/guides/api-governance/governing-api-change/): Governance does not end at the first release. Which rules can check a change, what only a comparison between versions can tell you, and the alerts worth having.
10. [What to Look for in an API Governance Tool](https://routebase.dev/guides/api-governance/api-governance-tools/): Eight criteria that decide whether a governance tool is still running in a year, written as questions to ask rather than as a list of vendors.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.