api-design— agent skill

What this skill does

Applies REST and GraphQL design principles to produce or review an API contract. It covers resource modelling, URL conventions, HTTP semantics, request/response schemas, error formats, versioning strategy, and authentication patterns — producing OpenAPI-compatible snippets or GraphQL schema fragments.

When to use it

• User asks to "design an API", "review this API", or "define the endpoints for X".
• User wants to model resources and operations before writing implementation code.
• User needs an OpenAPI snippet or GraphQL schema fragment.
• User is establishing API conventions for a team or project.

Key concepts

REST principles

Error response format

Consistent error bodies across all endpoints:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "issue": "must be a valid email address" }
    ]
  }
}

GraphQL conventions

• Operations: query for reads, mutation for writes, subscription for real-time.
• Type names: PascalCase (OrderLine). Field names: camelCase (lineItems).
• Always paginate list fields using Relay-style connections (edges, node, pageInfo).
• Use input types for mutation arguments: input CreateOrderInput { ... }.
• Return a result union for mutations: type CreateOrderResult = Order | ValidationError.

Security checklist

• [ ] Authentication required on all non-public endpoints (JWT, OAuth2, API key).
• [ ] Authorisation checked at the resource level, not just the route.
• [ ] Input validated and sanitised before processing.
• [ ] Rate limiting applied.
• [ ] Sensitive data (PII, tokens) not returned in error messages or logs.
• [ ] HTTPS enforced; HTTP redirects to HTTPS or is rejected.

Instructions

1. Identify the API type. REST or GraphQL? If not stated, recommend based on use case (REST for CRUD-heavy APIs, GraphQL for flexible querying across related data).

1. Model the resources or types. Identify the entities involved and their relationships. Name them clearly.

1. Define the operations. For REST: map resources to endpoints and HTTP methods. For GraphQL: define queries, mutations, and types.

1. Design request/response schemas. Specify field names, types, and validation rules. Call out optional vs. required fields.

1. Define the error contract. Consistent error format across all operations.

1. Address versioning and authentication. State the versioning strategy and authentication mechanism.

1. Flag design concerns. Identify any REST anti-patterns, N+1 risks (GraphQL), or security gaps.

1. Produce the output using the format below.

Output format

REST — OpenAPI snippet

openapi: 3.1.0
info:
  title: [API name]
  version: 1.0.0

paths:
  /[resource]:
    get:
      summary: List [resources]
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/[Resource]'
        '401':
          $ref: '#/components/responses/Unauthorised'

  /[resource]/{id}:
    get:
      summary: Get [resource] by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    [Resource]:
      type: object
      required: [id, created_at]
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

  responses:
    Unauthorised:
      description: Missing or invalid credentials
    NotFound:
      description: Resource not found

GraphQL — Schema fragment

type Query {
  [resource](id: ID!): [Resource]
  [resources](filter: [Resource]FilterInput, first: Int, after: String): [Resource]Connection!
}

type Mutation {
  create[Resource](input: Create[Resource]Input!): Create[Resource]Result!
}

type [Resource] {
  id: ID!
  # fields
  createdAt: DateTime!
}

input Create[Resource]Input {
  # fields
}

union Create[Resource]Result = [Resource] | ValidationError

type ValidationError {
  message: String!
  fields: [FieldError!]!
}

Design notes

### Design decisions

- [Decision and rationale]

### Concerns / open questions

- [Anti-pattern, risk, or unresolved design question]

Examples

Example 1 — Order management REST API

Input: "Design a REST API for creating and managing orders. An order has line items, a customer, and a status."

Expected output: OpenAPI snippet with /orders (GET, POST) and /orders/{id} (GET, PATCH, DELETE) and /orders/{id}/line-items (GET, POST). Order schema with status enum. Error contract. Design note on whether to embed line items in the order response or use a separate endpoint.

Example 2 — GraphQL API review

Input: User shares a GraphQL schema where a User type has a posts field returning a plain list with no pagination.

Expected output: Concern flagged for missing pagination (N+1 and performance risk at scale). Suggested fix using Relay connection pattern. Note on missing input types for mutations.

Notes

• REST URLs identify resources, not actions. If a URL contains a verb (/createOrder, /getUser), it is an anti-pattern — model it as a resource operation instead.
• GraphQL is not a replacement for REST in all cases: file uploads, caching, and simple CRUD are often better served by REST.
• OpenAPI snippets in this skill are illustrative, not exhaustive. A full spec requires info, servers, and security sections.
• Do not design authentication schemes that store credentials in URLs (?api_key=...) — they appear in server logs and browser history.