api-design
/api-design
Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.
- Author
- Amey-Thakur ↗
- Repository
- AI-SKILLS ↗
- Licence
- MIT
- Last repository change
- 05.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.
Original author description
Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.
How it works
- Method
- Litmus tests
- Boundaries
SKILL.md preview
---
name: api-design
description: Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.
---
# API design
An API is a promise you keep for years. Design for the caller you cannot
see, then keep the promise boring.
## Method
1. **Start from the caller's sentence.** Write the code or request the
caller *wants* to make, before any implementation exists: `POST
/notebooks/{id}/share` or `client.notebooks.share(id)`. If the ideal call
is awkward to say, the design is wrong at the root.
2. **Name by domain, shape by convention.** Nouns for resources, verbs for
actions that are not CRUD. Same word for the same concept everywhere:
an API where "document", "file", and "source" mean one thing teaches
distrust of every name.
3. **Make the common case one call** with obvious defaults, and the rare
case possible with explicit options. Never make every caller pay a
configuration tax for flexibility one caller needs.
4. **Errors are API.** Every failure a caller can cause gets a distinct,
documented, stable error with: what went wrong, on which input, and what
to do. A caller should distinguish "you sent garbage" (4xx / typed
error), "we broke" (5xx), and "try later" without parsing prose.
5. **Design for the invalid states not to exist.** Required pairs travel in
one object; mutually exclusive options are one enum, not three booleans;
ids that must belong together are validated together. If misuse compiles
or returns 200, it will ship.
6. **Version from day one, break never.** Additive change is free (new
optional field, new endpoint). Breaking change (rename, meaning change,
removal) needs a version and a deprecation window. Before renaming a
field, remember: someone wrote a cron job against it.
7. **Paginate every list, bound every input.** Unbounded responses and
unbounded request sizes are outages on a delay.
## Litmus tests
- Can a caller learn the API from one example call plus type/shape
signatures, without reading your source?
- Is every operation idempotent that safely can be, and documented where it
cannot?
- Could you delete the docs page for defaults and have callers unaffected?
## Boundaries
Consistency with the existing API's conventions beats abstract elegance:
one surprising-but-uniform surface is kinder than a half-migrated ideal.
Note the inconsistency you would fix, then follow the house style.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Amey-Thakur/AI-SKILLS | 100 | MIT |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Database snapshot: 13.11.2026 · package version 01af97307cc9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api-and-interface-design
Design seams, APIs, config keys and schemas that are deep, hard to misuse, and safe to roll out and back. Use when adding or changing a contract. - 100api
RESTful API design patterns and best practices. Use when creating endpoints, designing APIs, or implementing routes. - 100http-api-guidelines
This skill encodes the organizational guidelines for designing, developing, and versioning HTTP APIs. Use it when reviewing, designing, or building HTTP APIs to ensure compliance with the agreed-upon standards. - 100api-design-rest
Rules for designing and implementing HTTP/REST APIs. Use when creating or reviewing endpoints, request/response shapes, status codes, error formats, pagination, filtering, versioning, idempotency, rate limiting, or API documentation. - 95api-and-interface-design
Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend. - 100reviewing-module-design
Reviews module and type design: cohesion and coupling (via connascence), encapsulation, hard-to-misuse interfaces, and making illegal states unrepresentable. Use when reviewing class/module structure, interfaces, type or data modeling, coupling, or API ergonomics for callers.