Skip to content
routebase

Blog

Practical writing on designing, mocking, testing, and shipping APIs — and making them ready for AI agents.

A small slate robot with a glowing mint visor reads one of two documentation pages. The page it reads is sharp and edged in mint under a badge showing 100 and A+, the other page is grey and blurred under a badge showing 58 and F

How We Got Our Docs to 100 on the Agent-Friendly Docs Scorecard

We took routebase.dev from 87 to 100 on the open Agent-Friendly Docs Scorecard in one day. What failed, the four fixes, and the CDN header detail that nearly broke it.

AI AgentsDocumentationllms.txt
A long diagonal row of matte slate cubes in which some positions stand empty, marked only by a thin mint outline on the ground, while several of the remaining blocks have turned into spheres, cylinders, a ring and a pyramid

Three Years Later: What Happened to 1,927 Public API Specs

We fetched 1,927 public OpenAPI specs again and compared each with its 2023 copy. About half had changed, and nine in ten breaking changes had no new major.

OpenAPIVersioningBreaking Changes
A single block suspended above two differently built recesses, resting in neither of them

Where Should Your OpenAPI Spec Live?

Repo or hosted is the wrong question. What decides whether your API has one contract or several is which copy the others derive from, and who runs that step.

OpenAPIAPI DesignDocumentation
A row of matte blocks, one of them outlined and lit while the others stay dark

Why API Style Guides Fail With Too Many Rules

Most style guides fail with too many rules, not too few. The work is deciding which rules stop a build, which leave a note, and which you will never enforce.

API DesignGovernanceOpenAPI
Two matte blocks seated into one another along a machined stepped joint, the seam between them lit

API Descriptions That Pass the Linter and Fail the Agent

A linter flags a missing description, not a useless one, and the useless one is what an agent chokes on. What to write, what to leave out, and how to test it.

AI AgentsOpenAPIAPI Design
A long stream of loose scattered cubes converging into one stacked platform outlined in light

Migrating from Postman to an OpenAPI-First Workflow

The Postman migration everyone postpones is mostly mechanical, and that is agent work. How an AI over MCP imports collections and rebuilds your assertions.

OpenAPIPostmanMigration
Two rows of cubes, one a glowing wireframe and one solid, running out of a single lit joint in different directions while the solid row breaks apart at its far end

Why Your OpenAPI Spec Drifts (and How to Catch It)

Every API contract decays once nothing enforces it. The four ways specs drift, why code generation does not save you, and how to make the spec true again.

OpenAPIContract TestingAPI Design
A grid of identical dark blocks each carrying the same lit panel, with a single block among them cracked open

Consistent Error Handling with RFC 9457 Problem Details

Why every API needs exactly one error shape, how RFC 9457 Problem Details provides it, and the conventions that make it stick across every endpoint.

API DesignError HandlingREST
A scattered heap of cubes on the left resolving into an ordered grid on the right, one cube in the grid lit from within

API Design Principles: A Practical Guide

Six design decisions that make or break an API, from resource modeling, naming, and idempotency to pagination, error formats, and versioning, with examples.

API DesignRESTGuide
A faceted sphere with a glowing core wired into a wall of identical ports, lit on only the three ports it connects to

Designing Agent-Ready APIs

AI agents are becoming API consumers. What that changes about API design, from descriptions as prompts and actionable errors to MCP as the new surface.

AI AgentsMCPAPI Design
A glowing wireframe cluster of cubes on the left projecting a beam into a solid, already-built grid of cubes on the right

Design-First vs. Code-First API Development

Two workflows for building APIs, and why the order you write the contract in changes everything downstream, from parallel work and review quality to drift.

API DesignWorkflowOpenAPI
A short stair bridging an older sand-colored platform to a newer one stacked above it, the joining step lit, the old platform dissolving into loose particles at its far edge

Versioning APIs Without Breaking Your Consumers

What actually counts as a breaking change, why additive evolution beats version bumps, and how to run a deprecation your consumers will forgive.

API DesignVersioningBreaking Changes

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.