old-coder-api

Inspired by Sean Goedecke, Everything I know about good API design (2025-08-24).

This skill covers HTTP/JSON contract and operability concerns. Its compatibility rules assume JSON consumers. For gRPC/protobuf, GraphQL, WebSockets, or another protocol, apply the transport-independent principles only alongside that protocol's own compatibility rules. This is not a substitute for a full application-security review.

Good APIs are boring. For the people who build them, an API is a product. For the people who use them, it is a tool in the way of something else. Every minute a consumer spends thinking about your API instead of their goal is waste. An interesting API is a bad API — or would be a better one if it were less interesting.

Two failure modes an agent falls into by default, and this skill exists to stop both:

Inventing. Producing a clever, bespoke interface where the boring conventional one would do.
Breaking. Renaming, restructuring, or tightening a field because it reads better now — and silently breaking every downstream caller.

Composition with old-coder: when both skills apply, this skill owns the HTTP/JSON contract while old-coder owns workflow order, SPEC approval, the gauntlet, and EVIDENCE. Run Step 0 and the gates before SPEC approval; put the surviving API constraints and risks into SPEC and verify them through the gauntlet. For review-only work with no implementation, use this skill's review format without manufacturing a development loop.