API Designer

API Designer

Overview

This skill helps you design HTTP/REST and GraphQL APIs that are predictable, evolvable, and pleasant to consume. It covers resource modeling, URI design, HTTP semantics, versioning, pagination, filtering/sorting, error contracts, idempotency, concurrency control, auth, rate limiting, and writing machine-readable contracts.

Keywords: REST, GraphQL, OpenAPI, Swagger, API design, endpoint, resource, versioning, pagination, cursor, idempotency, ETag, RFC 9457, Problem Details, rate limit, contract, HATEOAS, webhook.

Apply this skill whenever the user is creating, extending, or reviewing an API surface — not when they are merely calling an existing third-party API.

Decision: REST vs GraphQL vs RPC

Pick the style before designing details.

• REST — default for resource-oriented CRUD, public APIs, heavy caching needs, file uploads/downloads, and broad client tooling. Plays well with HTTP caching, CDNs, and standard status codes.
• GraphQL — choose when clients need flexible, nested data selection, when you have many client types with divergent data needs, or to avoid over/under-fetching. Costs: caching, rate limiting, and observability are harder; needs query-depth/complexity limits.
• gRPC / JSON-RPC — choose for internal service-to-service, low-latency, streaming, or strongly-typed contracts where browser reach is not required.

When unsure, default to REST and expose a small GraphQL layer later if client flexibility becomes a real pain point. See references/rest-checklist.md and references/graphql-checklist.md.

Workflow

Follow these steps in order. Do not jump to URLs or schemas before modeling resources.

1. Identify the domain nouns (resources). List the core entities and their relationships. Resources are nouns, not verbs. Group them into collections and members.
2. Define the resource representation. For each resource, decide its fields, types, which are read-only/required/nullable, and identifiers (prefer opaque string IDs over leaking DB primary keys).
3. Map operations to HTTP methods (REST) or queries/mutations (GraphQL). Use the safe/idempotent matrix in references/http-semantics.md. Avoid verbs in REST paths; model actions as sub-resources or status transitions.
4. Design the URL structure / schema. Lowercase, kebab-or-snake consistent, plural collections, nested only one level deep. See naming rules below.
5. Choose pagination, filtering, and sorting. Default to cursor pagination for large/changing datasets. Standardize query parameters.
6. Define the error contract. Adopt RFC 9457 Problem Details. One consistent shape across all endpoints. See references/error-design.md.
7. Add reliability semantics. Idempotency keys for unsafe-but-retryable POSTs, ETag/If-Match for optimistic concurrency, conditional requests for caching.
8. Specify cross-cutting concerns. AuthN/AuthZ, rate limiting + headers, versioning strategy, deprecation policy, CORS.
9. Write the contract. Produce OpenAPI 3.1 (REST) or SDL (GraphQL) as the source of truth. Use templates/openapi-3.1-template.yaml or templates/graphql-schema-template.graphql.
10. Validate. Run scripts/lint_openapi.py on the OpenAPI file to catch common design smells before review.

Naming & URL Rules (REST)

• Collections are plural nouns: /invoices, /users/{userId}/orders.
• A member is the collection plus an ID: /invoices/{invoiceId}.
• No verbs in paths. Bad: /getInvoice, /createUser. Good: GET /invoices/{id}, POST /users.
• Actions that don't fit CRUD become sub-resources or controllers: POST /orders/{id}/cancel, POST /messages/{id}/send. Prefer modeling state: PATCH /orders/{id} with { "status": "cancelled" } when it's a true state field.
• Nest at most one level. Beyond that, link by ID and offer query filters: prefer /comments?postId=42 over /users/1/posts/2/comments/3.
• Use hyphens in multi-word path segments (/billing-accounts), and be consistent with field casing (camelCase or snake_case) — pick one and never mix.
• Query params for filtering/sorting/pagination; path params for identity.