--- title: "API and Interface Design: review, setup & limitations · Undominated.ai" canonical: https://undominated.ai/skills/addyosmani-api-and-interface-design/ description: "Designs stable API contracts, consistent errors and retry-safe idempotency behavior." --- # API and Interface Design: review, setup & limitations · Undominated.ai > Designs stable API contracts, consistent errors and retry-safe idempotency behavior. [← Explore all skills](/skills/) DEVELOPMENT WORKFLOW / Addy Osmani # API and Interface Design Designs stable API contracts, consistent errors and retry-safe idempotency behavior. [See setup guidance ↓](#setup)[Original source ↗](https://github.com/addyosmani/agent-skills/tree/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design) SOURCE REVIEW Reviewed 2026-10-07 Evidence 3 linked sources Publisher Addy Osmani Licence [MIT ↗](https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/LICENSE) Revision 1401c8b8030e [Read what was—and wasn’t—checked ↓](#review) “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.” [Addy Osmani · upstream description ↗](https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design/SKILL.md) Our analysis follows below. 01 / THE REASONING ## Why this made the selection. - Explains atomic idempotency claims, payload-hash checks and explicit handling of an unknown downstream outcome. - Connects backwards-compatible schema changes with pagination, boundary validation and retention of retry keys. ### A good fit for - Designing a new public endpoint or module boundary - Reviewing a change to an existing contract ### Weigh up before choosing - Examples need project-specific transactions, authentication and failure recovery. Trusted internal types do not make stored user-controlled data intrinsically trustworthy. - Reviewed definition and licence are pinned; installation and real-task outcomes for this resource were not tested. 02 / THE REVIEW RECORD ## What we actually inspected. Source review has boundaries. A clear record is more useful than a “safe” badge. ### Material inspected - skills/api-and-interface-design/SKILL.md (complete frontmatter and body) - https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/LICENSE (applicable licence text) ### Our findings - Explains atomic idempotency claims, payload-hash checks and explicit handling of an unknown downstream outcome. - Connects backwards-compatible schema changes with pagination, boundary validation and retention of retry keys. - Reads and edits API schemas, handlers, tests and documentation through the host; examples include state-changing service code. ### Not established by this review - Host discovery, task execution and model quality were not tested. - Referenced helpers, sibling plugins and external service operations were not exhaustively audited or executed. The review applies to the material and revision named here. A newer upstream release can change its behavior. 03 / PUT IT TO WORK ## Add a skill to your workflow. [Upstream setup instructions ↗](https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/README.md) DOCUMENTED COMMAND npx skills@1.7.1 add https://github.com/addyosmani/agent-skills/tree/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design --skill api-and-interface-design Copy command ↗ Copying does not execute this command. It may retrieve a newer version than the reviewed source. - Use the exact reviewed directory/revision and select the intended host/project scope in Skills CLI. - Retain all supporting files; separately configure companion skills, runtimes and service credentials named in the definition. - Review the resulting diff and use an isolated target before any migration, deployment, load test or warehouse operation. ### Before you start - A repository and explicit API compatibility requirements; framework-specific documentation for the implementation. ### Compatibility Agent Skills-compatible hosts ### Host-mediated code, files and tools - Reads and edits API schemas, handlers, tests and documentation through the host; examples include state-changing service code. - The host enforces permissions; installing instructions does not itself create a sandbox. ### Cost model Source is available under the stated licence. Model usage, compute and connected services can incur charges. 04 / FOLLOW THE EVIDENCE ## The source trail. Our notes are separate from the original resource. Check upstream before adopting a new version. - [Skill definition ↗](https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design/SKILL.md) Checked 2026-10-07 https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design/SKILL.md Supports: summary, whySelected, limitations, access, review - [Repository licence ↗](https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/LICENSE) Checked 2026-10-07 https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/LICENSE Supports: Redistribution terms - [Install instructions ↗](https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/README.md) Checked 2026-10-07 https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/README.md Supports: Documented install command KEEP COMPARING ## Other approaches to consider. Related by category or shared topics. These are alternatives to inspect, not a measured quality order. [### Constraint-driven development ↗ Records project quality constraints with measured baselines, enforcement commands and reviewable exceptions.](/skills/addyosmani-constraint-driven-development/)[### Dispatching Parallel Agents ↗ Splits independent investigations into bounded agent assignments and checks their integration afterward.](/skills/obra-dispatching-parallel-agents/)[### Gradio App Builder ↗ A Gradio reference and example collection for building Python interfaces, event-driven layouts and chat demos.](/skills/huggingface-huggingface-gradio/) [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/) ## Continue your investigation - [Choose a toolkit](/tools/) - [Inspect execution hosts](/agents/) - [Check tool access](/mcp-servers/) - [Check project dependencies](/check-repo/)