Skip to content
routebase

Blog

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

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

Writing API Descriptions an LLM Can Actually Use

A linter can tell you a description is missing. It cannot tell you the description is useless — and that is the one an agent chokes on. What belongs in a description, what to leave out, and how to check whether it worked.

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 migration everyone postpones is almost entirely mechanical — and mechanical work is what agents are for. How an AI with an MCP connection imports your collections, rebuilds your assertions, and verifies its own work against your real API.

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 the moment it stops being enforced. The four ways specs drift from reality, why code generation doesn't save you, and how to turn your spec back into a source of truth.

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 — stable type URIs, validation extensions, safe detail fields — that make it stick.

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

The six design decisions that make or break an API: resource modeling, naming, idempotency, pagination, error formats, and versioning — with concrete 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 — descriptions as prompts, error messages agents can act on, and why MCP is the new integration 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: parallel work, review quality, and 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.