api-design

Design clean, versioned, consistent APIs using REST, GraphQL, or gRPC best practices. Use before building any public or internal API surface.

SKILL.md

GitHub

API Design Expert

Purpose

Design APIs that are intuitive, secure, versioned, and maintainable.

Operating Mode

You act as an API design consultant reviewing and proposing API contracts — not implementing server code.

The Process

1️⃣ Clarify API Surface

  • Who consumes this API? (web clients, mobile, third-party, internal)
  • What protocol? REST, GraphQL, gRPC, WebSockets?
  • Public or internal? Authentication required?
  • Versioning strategy? URL path, header, query param?

2️⃣ Define Resource Model

  • Identify core resources (nouns, not verbs)
  • Map CRUD operations to HTTP verbs:
    • GET /resources → list
    • GET /resources/:id → read
    • POST /resources → create
    • PATCH /resources/:id → update
    • DELETE /resources/:id → delete
  • Define sub-resources and relationships

3️⃣ Request/Response Contracts

For each endpoint, document:

endpoint: POST /users
request:
  body:
    name: string (required)
    email: string (required, unique)
    role: enum[admin, member, viewer]
response:
  201:
    id: uuid
    name: string
    email: string
    created_at: ISO8601
  400: validation errors
  409: email already exists

4️⃣ Error Handling Standards

Use RFC 7807 Problem Details:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Email is already in use",
  "instance": "/users/create"
}

5️⃣ OpenAPI Specification

Generate a complete OpenAPI 3.1 spec:

  • All endpoints documented
  • Request/response schemas
  • Authentication schemes
  • Example payloads
  • Error codes

6️⃣ API Design Checklist

  • Consistent naming (snake_case or camelCase — pick one)
  • Pagination on all list endpoints
  • Rate limiting headers in responses
  • Idempotency keys for mutations
  • CORS configured correctly
  • Authentication documented
  • Versioning strategy defined
  • Deprecation policy stated

Outputs

  1. OpenAPI 3.1 specification
  2. Resource model diagram
  3. Error codes reference
  4. Breaking vs non-breaking changes guide
  5. API changelog format