Skip to content
Get packs

API Design Principles

Guides the agent to design clear, consistent REST and GraphQL APIs with a FastAPI starter template

Source Download skill
Repository
wshobson/agents
Stars
42,095
Licence
MIT
Files
6 files

What it does

Once installed, the agent follows established rules for designing web APIs (the interfaces that let apps talk to servers). It covers REST conventions such as plural resource names, correct HTTP methods and status codes, pagination, and versioning, plus GraphQL schema practices such as avoiding N+1 queries and using cursor pagination. It can also offer a starter FastAPI template with pagination, filtering, and error handling as a reference for new code.

Great for

  • Backend developers designing a new REST or GraphQL API
  • Teams setting shared API standards or reviewing an API spec before building
  • Developers migrating from REST to GraphQL and wanting a checklist of trade-offs

Skip it if

  • Non-developers who need a finished API: the skill gives design guidance, not a deployable service
  • Production use of the template as-is: its CORS and TrustedHost settings allow all origins and hosts (marked TODO), which must be restricted before real deployment

Try asking

  • “Review this OpenAPI spec for REST design problems and naming inconsistencies”
  • “Design a REST API for an e-commerce orders service with pagination and versioning”
  • “Suggest a GraphQL schema for a blog with cursor-based pagination and deprecation handling”
  • “Create a FastAPI starter with user endpoints following our API standards”
Step-by-step guide: how to use API Design PrinciplesInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 6 original files, the MIT licence and an attribution note.

    api-design-principles.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip api-design-principles.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip api-design-principles.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Give the agent your existing API spec or code so it can review against the checklist rather than generic advice
  • Treat the rest-api-template.py file as a reference to adapt; review security settings like allowed origins and hosts before use
  • Ask for the checklist in assets/api-design-checklist.md to be applied to a specific endpoint for a concrete review

What's inside

  • assets/api-design-checklist.md
  • assets/rest-api-template.py
  • references/details.md
  • references/graphql-schema-design.md
  • references/rest-best-practices.md
  • SKILL.md

Redistributed unmodified from wshobson/agents under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.