skills / wshobson / agents / api-design-principles

API Design Principles

A standards-focused API architecture skill for designing and reviewing REST/GraphQL interfaces with versioning, error models, and developer ergonomics.

Source description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewin...

npx skills add https://github.com/wshobson/agents --skill api-design-principles
risk: lowinstall: CLIverified: 2026-02-13

On this page

Our added value (verification layer)

This page is not only a source mirror. We add reproducibility, risk controls, and operations guidance on top of the original skill definition.

  • Execution/Security/Maintainability scoring with explicit criteria
  • Compatibility matrix across runtime environments
  • Verification log with check commands and observed outcomes
  • Common failure fixes and rollback triggers for production safety

Overall score

87/100

Execution

88

Security

83

Maintainability

90

Quick install (universal)

Primary command for most environments:

npx skills add https://github.com/wshobson/agents --skill api-design-principles

Manual fallback (if your runtime does not support direct installer command):

  1. npx -y skills add https://github.com/wshobson/agents --skill api-design-principles -y -g
  2. Restart your current agent/runtime to reload installed skills.
  3. Run a dry run: "review this API spec and list 5 design improvements".
  • After install, restart your current agent/runtime so the skill is reloaded.
  • Run a dry-run task first (non-destructive) to verify the skill behavior before production use.

SKILL.md (source preview)

Short preview shown here to keep this page focused on our verification layer.

API Design Principles Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time. When to Use This Skill Designing new REST or GraphQL APIs Refactoring existing APIs for better usability Establishing API design standards for your team Reviewing API specifications before implementation Migrating between API paradigms (REST to GraphQL, etc.) Creating developer friendly API documentation Op...

View full SKILL.md source page →

Required permissions

file

Compatibility matrix

EnvironmentStatusNotes
Backend API project design phasepassStrong guidance for endpoint/schema architecture and versioning.
Existing API refactor workflowspassUseful for review and migration planning with concrete patterns.
No-code/non-technical contextpartialRequires technical API understanding to apply effectively.

Verification log

Canonical source exists locally

test -f ~/.agents/skills/api-design-principles/SKILL.md

Pass

result: pass

Install command template validated

npx -y skills add https://github.com/wshobson/agents --skill api-design-principles -y -g

Pass

result: pass

Frontmatter + full body extracted

read ~/.agents/skills/api-design-principles/SKILL.md and split description/body

Pass

result: pass

Security notes

  • Include auth and permission boundaries in API contract decisions.
  • Avoid leaking internal system details through error responses.
  • Apply versioning strategy to prevent breaking consumers unexpectedly.

Common failures and fixes

Endpoint naming inconsistent across services

Standardize noun-based resource naming and method semantics.

Client breakage after API updates

Adopt explicit versioning and deprecation policy before rollout.

Unclear error responses

Define a uniform error schema with codes and actionable messages.

Quick FAQ

How do I install this skill quickly?

Run npx skills add https://github.com/wshobson/agents --skill api-design-principles, then restart your runtime to reload skills.

What should I check before production rollout?

Confirm permissions, run a non-destructive dry run, and review rollback triggers.

What if install succeeds but actions do not run?

Verify SKILL.md location, restart runtime, and check environment/dependency readiness.

Recent changes

  • 2026-02-13: Added hot-skill page entry from Excel priority list.
  • 2026-02-13: Synced sourceDescription and originalSkillMd from local canonical install.
  • 2026-02-13: Added compatibility, fixes, and rollback guidance.

Rollback triggers

  • New API design introduces widespread backward-incompatible changes.
  • Consumer teams report unresolved integration breakages.
  • Security review flags authorization model gaps in API contract.

Known issues

Teams may over-standardize and slow delivery

Use lightweight defaults and only enforce rules with clear ROI.

GraphQL/REST hybrid complexity

Define boundary rules for when each paradigm should be used.

Related tutorials

Site references