api-design
Designs an interface other people will depend on — REST endpoints, RPC methods, library functions, CLI commands, event payloads. Use this whenever the user is adding a public endpoint, designing a library's surface, defining a message contract, or asking how something should be called. Also use before implementing anything other teams or external users will consume, because the cost of changing it later is the whole point. For implementing against an existing interface, use feature-implementation.
Target: Design & content creation. Automatically collected · unverified.
Excerpt from the author’s documentation
Extracted from a fixed version of SKILL.md in its original language. This is the author’s documentation; installation, compatibility and runtime results have not been verified by this site.
Read the original English text
Topics in the source
- API design
- 1. Model the domain, not the storage
- 2. Make the wrong call impossible
- 3. Design the errors as carefully as the successes
- 4. Plan for change on day one
- 5. Be boring and consistent
- 6. Decide the operational contract
- Report
An API is a promise. Implementation is cheap to change; a published interface is not, because every caller has to move with you. Design it as though you cannot change it, because roughly speaking you cannot. Design from the caller's side. Write the code that calls your API before you write the API. If that code is awkward, the design is wrong, and you have found out in two minutes instead of after three teams have integrated. The most common failure is exposing your database schema through HTTP. It couples every consumer to your internal structure, so a routine table split becomes everyone's migration. Name resources and operations in the language your users use, not your tables. If a caller must understand your persistence model to use the API, the abstraction has already failed. Done when: you could change the storage layer without touching the interface. Design so misuse does not compile, or fails immediately and clearly: Required things are required. Not optional-with-a-runtime-check. Enums over free strings for anything with a fixed set of values. Distinct types over booleans. create(user, true, false) is unreadable at the call site and easy to get backwards. No parameter whos
This is an excerpt. Refer to the complete source and its current requirements.
- Source repository
- OKHP3/skillz
- Source file
- community/api-design/SKILL.md
- Fixed revision
- 7b187777d42ab7bc7bab1e5f2c940cd3139ecebf
Sources and evidence
This record was collected automatically. Its documentation, suitability and runtime behavior have not been manually verified.
Author: OKHP3/skillz · original repository metadata. Documentation review: Not reviewed. Last source check: 2026-11-10T10:00:53.986Z.
Categories are inferred from names, descriptions and paths. They do not establish compatibility.
License and attribution
MIT. Third-party content and copyright remain with their authors. Refer to the original license and terms.
Original license ↗Synchronization, copying and user-reported success do not mark a resource as runtime-tested.
Limitations and notes
- Collecting metadata does not mean this site has installed, adapted, runtime-tested or security-reviewed the resource.