api-and-interface-design

Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating RE…

addyosmani 80k ↓ 14k MIT updated 26d ago

Claude Code

View source ↗

What it does

Designing new API endpoints
Defining module boundaries or contracts between teams
Creating component prop interfaces
Establishing database schema that informs API shape
Changing existing public interfaces
Be intentional about what you expose. Every observable behavior is a potential commitment.
Don't leak implementation details. If users can observe it, they will depend on it.

Requirements & configuration

| "We don't need pagination for now" | You will the moment someone has 100+ items. Add it from the start. |
| "PATCH is complicated, let's just use PUT" | PUT requires the full object every time. PATCH is what clients actually want. |
| "We'll version the API when we need to" | Breaking changes without versioning break consumers. Design for extension from the start. |
| "Nobody uses that undocumented behavior" | Hyrum's Law: if it's observable, somebody depends on it. Treat every public behavior as a commitment. |
| "Internal APIs don't need contracts" | Internal consumers are still consumers. Contracts prevent coupling and enable parallel work. |

Configuration: POST

Derived from the skill's own SKILL.md documentation · extracted 2026-07-23

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.

Source

Repository: https://github.com/addyosmani/agent-skills

api-and-interface-design FAQ

What does the api-and-interface-design skill do?

What does api-and-interface-design require?

| "We don't need pagination for now" | You will the moment someone has 100+ items. Add it from the start. | | "PATCH is complicated, let's just use PUT" | PUT requires the full object every time. PATCH is what clients actually want. | | "We'll version the API when we need to" | Breaking changes without versioning break consumers. Design for extension from the start. | | "Nobody uses that undocumented behavior" | Hyrum's Law: if it's observable, somebody depends on it. Treat every public behavior as a commitment. | | "Internal APIs don't need contracts" | Internal consumers are still consumers. Contracts prevent coupling and enable parallel work. | Configuration keys: POST.

How do I install api-and-interface-design?

Run: npx -y skills add https://github.com/addyosmani/agent-skills --skill api-and-interface-design --agent claude-code — the source lives at github.com/addyosmani/agent-skills.

Maintain api-and-interface-design?

Let people know it's listed here — add the badge (live metrics, light/dark aware) or a plain link to your README or docs.

[![api-and-interface-design on getagentictools](https://getagentictools.com/badge/skills/addyosmani-agent-skills-api-and-interface-design.svg)](https://getagentictools.com/skills/addyosmani-agent-skills-api-and-interface-design?ref=badge)

npx agentictools info skills/addyosmani-agent-skills-api-and-interface-design

The second line is the CLI lookup for this page — handy in READMEs and docs.