api-design-principles

Overview of api-design-principles skill

What api-design-principles helps you do

The api-design-principles skill is a design review and drafting aid for REST and GraphQL APIs. It is most useful when you need to turn a rough product requirement into a cleaner API shape, review an existing spec before implementation, or standardize how a team designs endpoints and schemas.

Best fit users and teams

Use api-design-principles if you are:

• designing a new public or internal API
• reviewing endpoint or schema proposals for consistency
• choosing between REST and GraphQL patterns
• trying to catch avoidable design mistakes before code is written
• creating lightweight API standards for a team

It is especially useful for backend engineers, tech leads, platform teams, and AI agents asked to propose API contracts rather than full implementations.

What makes this skill worth installing

The main value is not novelty; it is structure. The skill packages practical design guidance, a review checklist, REST examples, and GraphQL schema patterns into one reusable promptable workflow. Compared with an ordinary “design me an API” prompt, api-design-principles gives your agent better defaults around:

• resource naming and URL structure
• HTTP method semantics and status codes
• pagination, filtering, and versioning
• error shape consistency
• GraphQL schema organization, nullability, and input modeling

What it does not do

This is not an API gateway, code generator, or full governance framework. It will improve design quality and review coverage, but you still need your own rules for auth, domain constraints, compliance, and runtime operations. If you need implementation scaffolding, the included FastAPI template helps for REST only; the skill is stronger on design principles than end-to-end delivery.

How to Use api-design-principles skill

Install api-design-principles skill

Install the skill from the wshobson/agents repository:

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

If your agent environment supports skill discovery, then invoke api-design-principles when the task is about API shape, contract review, or paradigm selection rather than business logic implementation.

Read these files first

For fastest adoption, read the files in this order:

1. SKILL.md for scope and the built-in workflow
2. assets/api-design-checklist.md for review criteria
3. references/rest-best-practices.md for concrete REST conventions
4. references/graphql-schema-design.md for schema patterns
5. assets/rest-api-template.py if you also want a REST implementation example

This reading path matters because the checklist is the highest-signal artifact for actual review work, while the references give examples your agent can reuse in outputs.

Know the core inputs the skill needs

The api-design-principles skill works best when you provide:

• domain objects: users, orders, invoices, projects
• main user actions: create, list, update, search, approve
• client type: public third-party, internal web app, mobile, partner integration
• API style constraints: REST, GraphQL, or “help me choose”
• operational needs: pagination, filtering, versioning, rate limits, webhooks, real-time
• compatibility constraints: existing endpoints, legacy payloads, migration limits

Without this input, the agent will often produce generic endpoints or a shallow schema that looks clean but misses your actual usage patterns.

Turn a rough request into a strong prompt

Weak request:

• “Design an API for tasks.”

Better request:

• “Use api-design-principles to design a REST API for a task management product. Main resources: workspaces, projects, tasks, comments. Clients: web app and mobile app. Required features: pagination, filtering by status and assignee, partial updates, audit-friendly timestamps, stable error responses, and versioning. Avoid deep nesting. Return endpoint list, request and response examples, status codes, and design rationale.”

Why this is better:

• it names resources
• it gives client context
• it states must-have behaviors
• it adds constraints the skill can optimize around

Use it for REST design reviews

For REST work, ask the skill to evaluate:

• resource nouns vs action verbs
• shallow vs overly deep nesting
• method correctness for GET, POST, PUT, PATCH, DELETE
• status code choices
• query parameter design for filtering, sorting, and search
• pagination pattern choice
• versioning and deprecation strategy
• error response consistency

A practical prompt:

• “Run api-design-principles against this draft endpoint list and flag naming, method semantics, pagination, and error-handling issues. Rewrite only the parts that violate established conventions.”

This keeps the output focused and review-oriented instead of triggering a full redesign.

Use it for GraphQL schema design

For GraphQL, the skill is more useful when you ask for schema structure decisions, not just type lists. Good asks include:

• modular schema organization
• nullability decisions
• input and payload types
• query and mutation naming
• interface and union usage
• connection-style pagination
• field design for common client queries

A strong prompt:

• “Use api-design-principles to design a GraphQL schema for a B2B support platform. Include User, Ticket, and Comment types, cursor pagination, clear mutation inputs, and sensible nullability. Explain tradeoffs where fields should remain nullable.”

Decide between REST and GraphQL with the skill

If you are undecided, ask for a comparative recommendation tied to your product:

• request diversity across clients
• need for partial data selection
• caching and CDN friendliness
• learning curve for your team
• internal vs external developer audience

A useful prompt:

• “Apply api-design-principles for API Development to compare REST and GraphQL for an internal analytics platform used by web dashboards and automation scripts. Recommend one approach and include the operational tradeoffs.”

Use the checklist as a gate before implementation

The included assets/api-design-checklist.md is the best artifact for teams that want consistent reviews. Treat it as a pre-build gate:

• review every resource and operation
• verify pagination on all collections
• choose a versioning approach explicitly
• confirm error and status code behavior
• identify missing search, sort, or sparse-field patterns

This is where the skill adds real decision value: it helps you catch contract defects before implementation locks them in.

Reuse the REST template carefully

assets/rest-api-template.py is a helpful reference, but do not mistake it for a universal production starter. It demonstrates patterns like:

• FastAPI structure
• pagination and validation
• enum usage
• middleware placement
• consistent response handling

It also contains obvious production TODOs such as permissive CORS and trusted host configuration. Use it to see how design choices map into code, not as a drop-in secure default.

Common workflow for better output

A reliable api-design-principles usage workflow is:

1. describe product goals and actors
2. list resources and high-value operations
3. choose REST, GraphQL, or ask the skill to compare
4. ask for a first-pass contract
5. run a review pass using the checklist categories
6. refine around edge cases: pagination, errors, versioning, nullability
7. only then move to implementation

That sequence reduces churn because naming and contract semantics stabilize earlier.

api-design-principles skill FAQ

Is api-design-principles good for beginners?

Yes, if you already understand basic HTTP or GraphQL concepts. The skill is readable and example-driven, but it assumes you are making design decisions, not learning backend development from zero. Beginners will get more value if they use it to review drafts rather than invent an entire API from scratch.

What is the difference between api-design-principles and a generic AI prompt?

A generic prompt may produce plausible endpoints, but api-design-principles gives your agent a tighter review frame. It pushes toward consistent resource modeling, method semantics, status codes, pagination, and schema structure. That usually means less cleanup after the first draft.

When is api-design-principles a poor fit?

Skip it when your main need is:

• code generation across many frameworks
• protocol-specific guidance outside REST or GraphQL
• organization-specific compliance requirements
• deep auth or event-driven architecture design

In those cases, api-design-principles guide content can still help, but it should not be your only source of truth.

Does the skill help with existing APIs, not just greenfield design?

Yes. One of the best uses is API review for existing drafts or legacy cleanup. Feed it current endpoints or schema snippets and ask for a prioritized list of design issues, backwards-compatibility concerns, and low-risk improvements.

Is this skill opinionated about REST versus GraphQL?

It supports both, but not equally in implementation depth. REST guidance is reinforced by the checklist and a code template, while GraphQL guidance is stronger at schema patterns and design examples than runtime setup. If you need executable GraphQL scaffolding, you will need additional tooling.

How to Improve api-design-principles skill

Give domain reality, not abstract nouns

The fastest way to improve api-design-principles output is to describe real entities and workflows. “Users manage projects and invoices” is better than “build a business API.” Concrete domains let the skill make better decisions about resource boundaries, nesting, and mutation shape.

Specify what clients need to do most often

API design should follow usage. Tell the skill:

• the top read paths
• the most common write operations
• which filters matter
• whether clients need bulk operations
• whether mobile bandwidth or third-party integrations matter

This changes the output materially. For example, heavy list filtering and sparse retrieval push REST design differently than highly variable dashboard queries, which may favor GraphQL.

Ask for tradeoffs, not just a draft

Many weak outputs come from asking for “an API design” without asking why. Improve results with prompts like:

• “Propose two designs and compare tradeoffs.”
• “Flag any endpoint that violates REST semantics.”
• “Explain why fields are nullable or non-null in GraphQL.”
• “Show where versioning will hurt us later.”

This forces the skill to expose reasoning instead of generating polished but brittle contracts.

Use the checklist categories as revision prompts

If the first output is generic, iterate by section:

• “Revise only resource naming and URL hierarchy.”
• “Now review status codes and error format.”
• “Now add pagination, filtering, and sorting rules.”
• “Now review versioning and deprecation.”

The checklist file is effective because it turns quality into inspectable dimensions rather than one vague “make it better” request.

Watch for common failure modes

The main failure modes when using api-design-principles install successfully but getting weak output are:

• missing domain constraints
• no target client context
• asking for both REST and GraphQL without a decision goal
• no compatibility requirements for existing APIs
• no examples of the payload shape you expect

These lead to generic resources, awkward nesting, vague error handling, and shallow schema design.

Validate outputs against your actual constraints

Before adopting any proposal from api-design-principles for API Development, check:

• can your auth model support these operations?
• do your clients need stable IDs and timestamps everywhere?
• are collections paginated by default?
• do error shapes match platform conventions?
• does versioning fit your release process?
• are nullable GraphQL fields intentional?

The skill improves design quality, but your team still owns the contract.

Improve team adoption with a lightweight review standard

If you want lasting value, convert the skill into a team practice:

• use the checklist in pull requests for API specs
• require rationale for versioning and pagination choices
• document one naming convention for resources and mutations
• review one reference file when introducing new patterns

That makes api-design-principles usage repeatable instead of a one-off prompt that only one engineer knows how to use.