Menú
Design APIs that are stable, ergonomic, and evolvable
| name | api-and-interface-design |
| description | Design APIs that are stable, ergonomic, and evolvable |
| difficulty | senior |
| domains | ["general"] |
APIs are promises. Once published, they are hard to break without breaking callers. This skill designs APIs that are easy to use correctly, hard to use incorrectly, and evolvable without breaking changes.
Your internal data model should not dictate your API shape. Design for the use case: what does the caller need to do? What information do they have? What do they want back?
Naming, parameter order, error formats, and response shapes should be consistent across the entire API. Consistency is worth more than local elegance.
A caller should be able to guess how to use the API without reading the documentation for the common cases. Reserve documentation for edge cases.
Every error must tell the caller: what went wrong, which field caused it (for validation errors), what they can do to fix it. "Bad request" is not an error message.
Build versioning into the API from the first version: /v1/users, not /users. Retrofitting versioning is painful.
Document: authentication method, rate limits, request/response schema, error codes, pagination pattern, time formats, ID formats.
"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." Design carefully; change carefully.
Build UIs that work for all users including keyboard navigation, screen readers, and WCAG 2.2
Design multi-agent systems with robust tool interfaces, state management, and failure handling
Build ML systems with disciplined training, evaluation, deployment, and safety practices
Design systems at the right scale with explicit trade-off documentation
Design services that are reliable, observable, secure, and maintainable
Design CI/CD pipelines with fast feedback, quality gates, and reliable deployments
