Api design
Plug-and-play skills and prompts for every AI coding agent
npx -y skills add Amey-Thakur/AI-SKILLS --skill api-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 18 days oldThe repository was created 18 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
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.
SKILL.md
2.5 KB, as published. Nobody here has run it
API design
An API is a promise you keep for years. Design for the caller you cannot see, then keep the promise boring.
Method
- Start from the caller's sentence. Write the code or request the
caller wants to make, before any implementation exists:
POST /notebooks/{id}/shareorclient.notebooks.share(id). If the ideal call is awkward to say, the design is wrong at the root. - 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.
- 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.
- 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.
- 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.
- 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.
- 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.