API Design

Design APIs that are clear, evolvable, and idiomatic to their protocol — covering REST (Fielding, Richardson Maturity Model, Massé), GraphQL, gRPC/protobuf, versioning strategies, pagination, error responses (RFC 7807 Problem Details), idempotency, authentication, documentation (OpenAPI), and the pragmatic trade-offs between RESTful purity and developer ergonomics. Use when designing a new endpoint, choosing between REST/GraphQL/gRPC, defining versioning, structuring error responses, deciding pagination strategy, or evaluating an existing API's evolvability.

5 stars 2 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add vnovakovits/claude-skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add vnovakovits/claude-skills --skill api-design
Manual install
git clone --depth 1 https://github.com/vnovakovits/claude-skills.git /tmp/claude-skills
mkdir -p ~/.claude/skills
cp -r /tmp/claude-skills/plugins/engineering-practices/skills/api-design ~/.claude/skills/api-design

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# API Design

Apply this skill when designing any API — internal or public, REST or GraphQL or RPC. The goal is clarity for consumers, evolvability for the producer, and operational sanity for everyone.

## Core Philosophy

**APIs are forever.** Internal APIs you can refactor; public APIs you cannot. Design assuming external consumers will outlive the team that built it.

**Consumers are the product.** An API is a user interface for developers. Optimize for the developer reading it for the first time, not the engineer who wrote it.

**Be conservative in what you send; liberal in what you accept.** Postel's Robustness Principle. Tolerate input variations; emit strict, predictable output. (Caveat: liberal acceptance can also enable abuse — see "When Postel goes wrong" below.)

**Evolve, don't break.** Breaking changes are expensive and usually unnecessary. Most "redesigns" can be additions that leave old shapes intact.

**Pragmatism beats purity.** RESTful purity is a tool, not a religion. When a small deviation (an action-style endpoint, a non-standard verb) produces a clearer API, take it — but document the deviation.

---

## Choosing the Protocol

Different problems want different protocols. The three dominant choices:

### REST
**Best for:** public APIs, resource-oriented domains, web-friendly clients, caching-friendly read patterns.
- HTTP-native. Verbs match operations. Status codes match outcomes. Caches work.
Read the full skill on GitHub

Details

Skill name
api-design
Path
plugins/engineering-practices/skills/api-design/SKILL.md
License
MIT
Repo updated
16 November 2026

FAQ

What does the API Design skill do?

Design APIs that are clear, evolvable, and idiomatic to their protocol — covering REST (Fielding, Richardson Maturity Model, Massé), GraphQL, gRPC/protobuf, versioning strategies, pagination, error responses (RFC 7807 Problem Details), idempotency, authentication, documentation (OpenAPI), and the pragmatic trade-offs between RESTful purity and developer ergonomics. Use when designing a new endpoint, choosing between REST/GraphQL/gRPC, defining versioning, structuring error responses, deciding pagination strategy, or evaluating an existing API's evolvability.

How do I install the API Design skill?

Claude Code plugin: /plugin marketplace add vnovakovits/claude-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is API Design popular?

It lives in vnovakovits/claude-skills, which has 5 GitHub stars and 2 forks.

Related skills

Accidental Cio

5

vnovakovits/claude-skills

Apply Scott Millett's "The Accidental CIO — A Lean and Agile Playbook for IT Leaders" (Wiley, 2024) when designing or reviewing how a technology organisation decides, funds, governs and delivers work. Covers the five components of an adaptive IT operating model (organised, work, govern, talent, lead) and its four themes (outcomes over output, intrinsic motivation, being not doing agile, manage flow not people); matching method and governance to context via Cynefin and Wardley evolution; governance as demand management + funding + measurement + decision rights, shifting from project funding to

Frontend & Design

Agent Retro

5

vnovakovits/claude-skills

Run a retrospective on a coding-agent session and improve the agent's environment, not the code. Combines Derby & Larsen's five-stage retrospective, Shigeo Shingo's poka-yoke (turn a mechanical mistake into a check that makes it impossible), and Matt Pocock's retro categories — navigation, automated checks, coding standards, steering files, tool economy, information access. Covers mining the session transcript for corrections, wrong turns and slow searches; deciding where each fix belongs (analyzer, hook, CI, reviewer standards, CLAUDE.md pointer, skill, doc or memory); the no-op test for stee

AI, LLMs & Agents

Architecture Decision Records

5

vnovakovits/claude-skills

Apply Michael Nygard's Architecture Decision Records (ADRs) — lightweight, immutable Markdown documents that capture significant architectural decisions, their context, and their consequences. Covers Nygard's classic format, MADR, when a decision is "architecturally significant", supersession workflow, where to store ADRs, and how to use them as living institutional memory. Use when making a significant technical decision, when joining a project and wondering "why was it built this way", when a past decision starts to bite, or when a team's tribal knowledge is bleeding away through personnel t

Software Development

Airtable Master

8

Freddy-CHEN-ux/00_claude_skills

Shared resource library for Airtable integration skills. DO NOT load directly - provides common references (setup, API docs, error handling, field types) and scripts used by airtable-connect, airtable-query, and airtable-sync.

Software Development

Beam Master

8

Freddy-CHEN-ux/00_claude_skills

Shared resource library for Beam AI integration skills. DO NOT load directly - provides common references (setup, API docs, error handling, authentication) and scripts used by beam-connect and individual Beam skills.

Software Development

Add Integration

8

Freddy-CHEN-ux/00_claude_skills

Build a new API integration for Nexus. Load when user mentions "add integration", "new integration", "integrate with", "connect to [service]", or "build [service] integration". Interactive workflow that discovers API endpoints, plans the integration, and creates a project for implementation.

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.