Skip to content
Skills Library
Programming · Planning

api-design

/api-design

Use when designing, reviewing, or planning REST or GraphQL APIs — endpoint structure, schema design, versioning, error handling, pagination, URI naming, or choosing between REST and GraphQL. Also triggers for OpenAPI spec creation and API contract review.

Repository
skills ↗
Licence
CC0-1.0
Last repository change
20.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

CC0-1.0, otwarta.

What it does and when to use it

Use when designing, reviewing, or planning REST or GraphQL APIs — endpoint structure, schema design, versioning, error handling, pagination, URI naming, or choosing between REST and GraphQL. Also triggers for OpenAPI spec creation and API contract review.

Original author description

Use when designing, reviewing, or planning REST or GraphQL APIs — endpoint structure, schema design, versioning, error handling, pagination, URI naming, or choosing between REST and GraphQL. Also triggers for OpenAPI spec creation and API contract review.

How it works

  1. When to Use
  2. Invocation Notice
  3. Universal Principles
  4. Route by Task
  5. Quick Decision: REST vs GraphQL
  6. Common Mistakes
Original SKILL.md headings · 94 lines, 887 words
SKILL.md preview
---
name: api-design
description: |-
  Use when designing, reviewing, or planning REST or GraphQL APIs — endpoint structure, schema design, versioning, error handling, pagination, URI naming, or choosing between REST and GraphQL. Also triggers for OpenAPI spec creation and API contract review.
---

# API Design

## When to Use

- Designing new API endpoints or schemas
- Reviewing existing API contracts for consistency
- Choosing between REST and GraphQL for a project
- Planning versioning, pagination, or error handling strategies
- Creating or reviewing OpenAPI/GraphQL specifications
- Naming URIs, fields, or resources
- Reviewing API security posture

**When NOT to use:**

- Framework-specific implementation details (though FastAPI patterns are available as a secondary reference below)
- Database schema design (unless it directly affects the API contract)
- Frontend data fetching code (unless reviewing the API contract it consumes)

## Invocation Notice

- Tell the user when this skill is running: `api-design`.
  Skip the notice when the user asked for the skill by name or slash command; spelling and spacing need not match.
  A phrase from this skill's own trigger list is not a name — naming the work is not naming the skill.

## Universal Principles

These apply regardless of REST or GraphQL:

1. **Prefer design-first for public, cross-team, or governance-heavy APIs.**
   Write the contract (OpenAPI spec or GraphQL schema) before implementation.
   Code-first is the normal workflow for frameworks like FastAPI that generate the contract from code, and is acceptable for rapid prototypes or internal tools with stable requirements.
   The choice is driven by governance needs, not protocol correctness.
2. **Consistency is non-negotiable.**
   Pick conventions and apply them uniformly across every endpoint, field, and error response.
3. **API surface is not database surface.**
   Never mirror internal data models in public contracts.
   Abstract so you can change internals without breaking clients.
   See [rest-design.md § API Surface Is Not Database Surface](references/rest-design.md) for rationale, anti-patterns, and decoupling strategies.
4. **Validate and shape at the boundary.**
   Enforce input constraints and response shaping at the API boundary.
   Authenticate before business logic runs.
   As a strong default, keep fine-grained authorization policy in the domain/business layer — but coarse access control (e.g., "only authenticated users") is legitimately enforced in gateways or middleware before the domain layer.
5. **Evolve without breaking.**
   Hyrum's Law: with enough users, every observable behavior of your API — including undocumented quirks, error message text, and field ordering — becomes a de facto contract someone depends on.
   Design with that in mind: be intentional about what you expose, and treat any change as potentially breaking until proven otherwise.
   Additive changes are usually safe, but verify compatibility against clients — adding a GraphQL enum value is schema-safe yet can surprise clients that assume exhaustive handling.
   Removal, renaming, and type changes require versioning (REST) or deprecation workflows (GraphQL).
6. **Security is structural.**
   HTTPS, authentication, authorization, rate limiting, and input validation are not optional additions — they are part of the design.

Use the references below as scoped guidance.
Some references describe broad consensus, while others document strong defaults or ecosystem-specific patterns.

## Route by Task

| Design Task                          | Reference                                                     | When to Load                                               |
| ------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------- |
| REST vs GraphQL decision             | [rest-vs-graphql.md](references/rest-vs-graphql.md)           | Starting a new API or evaluating a paradigm shift          |
| REST endpoint design                 | [rest-design.md](references/rest-design.md)                   | Designing REST resources, methods, status codes            |
| GraphQL schema/query/mutation design | [graphql-design.md](references/graphql-design.md)             | Designing GraphQL types, queries, mutations, subscriptions |
| URI/URL naming                       | [uri-design.md](references/uri-design.md)                     | Naming endpoints, path segments, query parameters          |
| API versioning                       | [versioning.md](references/versioning.md)                     | Planning version strategy, deprecation, migration          |
| Error responses                      | [error-handling.md](references/error-handling.md)             | Designing error formats, status code usage, RFC 9457       |
| Pagination and filtering             | [pagination-filtering.md](references/pagination-filtering.md) | Lists, collections, search results, sorting                |
| FastAPI implementation               | [fastapi-practices.md](references/fastapi-practices.md)       | Building APIs with FastAPI specifically                    |

**How to use this table:** Load only the references relevant to the current task.
For a new API design, start with `rest-vs-graphql.md`, then load the paradigm-specific reference.
For targeted questions (e.g., "how should we version this?"), load only that reference.

## Quick Decision: REST vs GraphQL

- **REST:** simpler caching, lower learning curve, native file uploads, smaller security surface.
- **GraphQL:** client-specified queries, nested data without over-fetching, built-in subscriptions — but requires depth/cost limiting, custom caching, and more schema governance.
- **Hybrid:** can work, but increases operational and governance complexity.
- **Caution:** GraphQL was not designed for file uploads; use multipart workarounds or a separate REST endpoint.
  REST requires careful endpoint design to avoid N+1 orchestration.

For the full decision tree and tradeoff matrix, load [rest-vs-graphql.md](references/rest-vs-graphql.md).

## Common Mistakes

| Mistake                                                    | Fix                                                                                                                                                          |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Verbs in REST URIs (`/getUsers`, `/createOrder`)           | Use nouns + HTTP methods for CRUD; verbs only for [controller resources](references/rest-design.md) (`POST /orders/{id}/cancel`)                             |
| Exposing database IDs/structure in API                     | Abstract with slugs, UUIDs, and [domain-oriented shapes](references/rest-design.md); use a mapping layer, not auto-serialization                             |
| Inconsistent error formats across endpoints                | Define one error schema, use it everywhere                                                                                                                   |
| No pagination on collection endpoints                      | Paginate unbounded or growth-prone collections; small bounded reference data may not need it — always set default and max page sizes when pagination is used |
| Breaking changes without versioning                        | Use additive changes; version when breaking is unavoidable                                                                                                   |
| Generic GraphQL mutations (`updateEntity`)                 | Use specific semantic mutations (`publishPost`, `archiveOrder`)                                                                                              |
| Auth logic in resolvers/handlers instead of business layer | Delegate authorization to domain services                                                                                                                    |
| Nullable everything / non-null everything                  | Be intentional: non-null only when you can guarantee presence                                                                                                |
Files in this package (10)
  • SKILL.md 8 KB
  • references/.gitignore 1 KB
  • references/error-handling.md 8 KB
  • references/fastapi-practices.md 11 KB
  • references/graphql-design.md 10 KB
  • references/pagination-filtering.md 9 KB
  • references/rest-design.md 14 KB
  • references/rest-vs-graphql.md 7 KB
  • references/uri-design.md 6 KB
  • references/versioning.md 7 KB

Versions

RepositoryScoreLicence
This page · ahgraber/skills90CC0-1.0
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

Database snapshot: 13.11.2026 · package version f61c4a28b709 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-designer
    Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
  • 100design-api
    Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract".
  • 100api-designer
    Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
  • 100api-design-principles
    Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs.
  • 100api-design-expert
    Expert API design for REST & GraphQL: resource modeling, status codes, versioning, pagination, idempotency, errors, and contracts. Trigger keywords: API design, REST, RESTful, GraphQL, OpenAPI, endpoint, status code, versioning, pagination, cursor, idempotency, rate limit,…
  • 100api-designer
    Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.