API Design

Overview

APIs are contracts. Broken contracts break everyone downstream. Fixing a shipped API is ten times harder than designing it right.

Core principle: DESIGN THE API CONTRACT BEFORE IMPLEMENTING THE HANDLER. Implementation details leak into APIs when you code first.

Violating the letter of this process is violating the spirit of API design.

The Iron Law

DESIGN THE API CONTRACT BEFORE IMPLEMENTING THE HANDLER

If you haven't written the OpenAPI spec (or equivalent contract), you cannot write handler code.

When to Use