---
name: gh-api-design
description: "Designs an API with explicit decisions on contracts, versioning, errors, and the mistakes that are hard to undo."
---
# /gh-api-design

APIs are the decisions you can't take back. A bad URL structure, an inconsistent error format, or a response shape that leaks implementation details — these live forever because changing them breaks callers. Design before building is 10x cheaper than design after.

Design the API described in this conversation.

**What this API does**
One paragraph: who calls it, what it enables, what it explicitly does not do. Scope matters — an API that tries to do everything does nothing well.

**Endpoints**
For each endpoint:
- Method + path (follow REST conventions or justify deviation)
- Request: required fields, optional fields, types, constraints
- Response: shape with field names and types (happy path)
- Errors: every failure condition, with status code and error body shape
- Auth: what authentication is required

**Design decisions — the ones that are hard to change later**
For each decision, state the choice and why:
- Versioning strategy — URL versioning, header versioning, or none
- Pagination — cursor or offset, response envelope shape
- Error format — what every error response looks like (be consistent)
- ID format — UUID, integer, slug — and why
- Naming conventions — camelCase vs snake_case, singular vs plural

**What could go wrong**
- Where will this API be misused or called in ways you didn't intend?
- What happens when load is 10x what you expect?
- What breaking changes are you likely to need in 6 months?

**What to build first**
If this is a new API: the minimal contract that enables the first real use case. Don't design the full API upfront — design what you need now with room to extend.

Rules:
- Consistency is more important than perfection — one bad convention applied everywhere beats 5 good conventions applied inconsistently
- Every error condition must have a documented response — silent failures are not acceptable
- If a design decision is reversible, say so. If it isn't, flag it clearly