# Old Coder API

Design, change, or review an HTTP/JSON API surface, endpoints, request/response...

- Repository: https://github.com/AmazingAng/old-coder (753 stars)
- Category: Design
- License: MIT
- Last updated: 2026-08-18
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AmazingAng/old-coder --skill old-coder-api -g -a claude-code -y`
Codex: `npx skills add AmazingAng/old-coder --skill old-coder-api -g -a codex -y`
Cursor: `npx skills add AmazingAng/old-coder --skill old-coder-api -g -a cursor -y`
Gemini CLI: `npx skills add AmazingAng/old-coder --skill old-coder-api -g -a gemini-cli -y`

## Description

Design, change, or review an HTTP/JSON API surface, endpoints, request/response shapes, authentication and authorization, pagination, idempotency, rate limits, versioning, and deprecations. Use when adding or modifying an HTTP endpoint, reviewing an OpenAPI spec or HTTP route diff, or deciding whether an HTTP API change breaks consumers. Do not use as a protocol-compatibility checklist for gRPC/protobuf, GraphQL, WebSockets, or other non-HTTP/JSON interfaces.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

1. **Inventing.** Producing a clever, bespoke interface where the boring conventional one would do.
2. **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.

## Step 0, establish scope before designing anything

Answer these three, out loud, before writing a route:

The rest: https://github.com/AmazingAng/old-coder/blob/HEAD/skills/old-coder-api/SKILL.md