skill: api-design

should_trigger:
  - prompt: "Design the REST API for a multi-tenant invoicing service"
    why: core greenfield contract-design request; resource modeling + URLs.
  - prompt: "How do I add a field and a new status value to this endpoint without breaking existing clients?"
    why: evolution/versioning; non-obvious — no words 'API' or 'design', it's the additive-non-breaking rule.
  - prompt: "Should this be REST or GraphQL, and how should pagination work?"
    why: paradigm choice plus pagination convention — both are design-time decisions.
  - prompt: "What's the standard error format? I keep returning a different shape per endpoint"
    why: symptom-led; routes to the single RFC 9457 problem-details envelope.
  - prompt: "Our list endpoint times out at page 5000 with offset pagination"
    why: non-obvious symptom — the fix is a cursor/keyset pagination design, not a query tweak.
  - prompt: "diseña los endpoints y el versionado de nuestra API pública"
    why: Spanish trigger for endpoint design + versioning strategy.
  - prompt: "We need an Idempotency-Key on POST so retries don't double-charge — how should the contract handle it?"
    why: non-obvious header-level contract decision (idempotency), design-time not implementation.

should_not_trigger:
  - prompt: "Implement these endpoints in FastAPI with Pydantic models and async routes"
    route_to: fastapi
    why: build-time framework implementation, not contract design.
  - prompt: "Threat-model this endpoint and check the CORS and CSP config for OWASP issues"
    route_to: secure-coding
    why: security/hardening lens, not the API shape.
  - prompt: "Verify the incoming Stripe webhook signature and dedupe replayed events"
    route_to: webhooks
    why: receiving inbound events with HMAC verification, not designing an exposed API.
  - prompt: "Write a client that calls the OpenWeather API and handles its rate limits and retries"
    route_to: api-connector-builder
    why: building an outbound client to a third-party API, not designing one.
  - prompt: "Wire a custom provider with useFactory in my NestJS module"
    route_to: nestjs
    why: framework dependency-injection wiring, not contract design.

capability:
  - scenario: "Design the public REST API contract for a 'projects' resource with nested tasks, supporting pagination, consistent errors, and a versioning plan."
    must_include:
      - plural noun collections and nested path `/projects/{id}/tasks` with no verbs in paths
      - correct methods + status codes, including 201 + Location on create and the 409-vs-422 distinction
      - one RFC 9457 `application/problem+json` error envelope used across all endpoints, with a stable machine `type` and a correlation id, no leaked internals
      - cursor (keyset) pagination with a consistent response envelope (data + next_cursor/has_more)
      - URL-path versioning for the public API plus the additive-non-breaking evolution rule (and Deprecation/Sunset on removal)
      - a handoff note pointing to a framework skill (fastapi/nestjs/go/nodejs) to implement it
      - bonus: an OpenAPI 3.1 sketch of the contract

# Evals: api-design

These cases are run by the repository's eval harness against the skill router. `should_trigger` asserts that for each prompt the router selects `api-design`; `should_not_trigger` asserts the named sibling wins instead (each `route_to` is a real catalog id); `capability` is a rubric-graded generation check — the model is asked the scenario and its output is scored against the `must_include` list. Run them with the repo's eval runner pointed at `cases.yaml`; no network or live API is needed.

# GraphQL design

When you chose GraphQL (many client shapes, deep graphs, over-fetch is real), design the schema as the contract. Framework-neutral.

## Schema & nullability

- **Model the domain graph, not your tables.** Types are nouns with relationships; let clients traverse instead of you minting endpoints.
- **Nullability is a contract.** A non-null field (`String!`) means the resolver must always produce it — and if it errors, GraphQL nulls the *nearest nullable parent*, which can blank a whole subtree. Make a field non-null only when it truly cannot be absent; default to nullable for anything fetched from a flaky downstream.
- **Use enums for closed sets** and add values additively (clients should tolerate unknown enum values).
- **Evolve additively; deprecate with `@deprecated(reason: ...)`** instead of removing — GraphQL has no URL version to fall back on.

## Pagination: Relay Connections

Use the de-facto standard rather than a bespoke shape, so client tooling (Apollo/Relay) works out of the box.

```graphql
type ProjectConnection {
  edges: [ProjectEdge!]!
  pageInfo: PageInfo!
}

type ProjectEdge {
  node: Project!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

type Query {
  projects(first: Int!, after: String): ProjectConnection!
}
```

- `first` + `after` paginate forward; `last` + `before` backward.
- `cursor` is opaque — clients pass `endCursor` back as `after`; they never construct it.

## Mutations & error model

- **One input object per mutation, one payload type out** — keeps mutations evolvable: `createProject(input: CreateProjectInput!): CreateProjectPayload!`.
- **Model expected, business-level failures as data, not as protocol errors.** A union or a payload with `userErrors { field, message }` lets clients handle validation without parsing the transport `errors[]`.

```graphql
type CreateProjectPayload {
  project: Project
  userErrors: [UserError!]!
}
```

## The HTTP-200 error model (the big operational difference)

GraphQL returns **HTTP 200 even when a field errored.** Failures appear in a top-level `errors[]` array alongside partial `data`:

```json
{
  "data": { "project": null },
  "errors": [
    { "message": "Project not found", "path": ["project"], "extensions": { "code": "NOT_FOUND" } }
  ]
}
```

Consequences you must design for:
- **Monitoring cannot rely on HTTP 5xx.** Alerting must inspect the `errors[]` payload and `extensions.code`, not the status line. Wire this before launch or outages go invisible.
- **Clients must check `errors[]` on every response**, even a 200. Treating 200 as success silently swallows failures.
- **Standardize `extensions.code`** (e.g. `NOT_FOUND`, `FORBIDDEN`, `VALIDATION`) so clients and dashboards branch on a stable machine value — the GraphQL analogue of an RFC 9457 `type`.

This single difference, not the query syntax, is what makes GraphQL operationally distinct from REST. Decide it explicitly.

# OpenAPI 3.1 contract

The contract is the artifact. Capture a REST design as an **OpenAPI 3.1** document — a real, lintable file that a framework skill generates server stubs and clients from, and that `scripts/verify.sh` checks.

Why 3.1: it aligns with JSON Schema 2020-12, so your request/response schemas are reusable JSON Schema, and it adds `webhooks` and richer `$ref` handling over 3.0.

## Minimal skeleton

```yaml
openapi: 3.1.0
info:
  title: Projects API
  version: 1.0.0
servers:
  - url: https://api.acme.com/v1
paths:
  /projects:
    get:
      summary: List projects
      parameters:
        - { name: cursor, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, maximum: 100, default: 50 } }
      responses:
        "200":
          description: A page of projects
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ProjectPage" }
        default:
          $ref: "#/components/responses/Problem"
    post:
      summary: Create a project
      parameters:
        - { name: Idempotency-Key, in: header, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ProjectCreate" }
      responses:
        "201":
          description: Created
          headers:
            Location: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Project" }
        "422": { $ref: "#/components/responses/Problem" }
        default: { $ref: "#/components/responses/Problem" }
components:
  responses:
    Problem:
      description: RFC 9457 problem details
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
  schemas:
    Problem:
      type: object
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }
      required: [type, title, status]
    ProjectPage:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/Project" } }
        next_cursor: { type: [string, "null"] }
        has_more: { type: boolean }
      required: [data, has_more]
```

## Conventions that keep it clean

- **One reusable `Problem` schema and `Problem` response**, referenced by every error case — enforces the single RFC 9457 envelope.
- **A `default` response on every operation** so unexpected statuses still resolve to the problem shape.
- **Every list operation carries `cursor` + `limit`** params — verify.sh warns when a list path lacks them.
- **No verbs in path keys** — verify.sh flags `/get*`, `/create*`, `/delete*` segments.
- **`info.version` is the contract version**, distinct from the URL `/v1` major; bump it on any non-breaking addition too.

## Handoff

Give the framework skill this file. It becomes the source of truth: FastAPI/NestJS/Go/Node tooling can generate models, route stubs, and validation from it, and clients can generate SDKs. Keep the OpenAPI doc updated *before* the code changes — design-first, not code-first.

# REST conventions

Depth behind the SKILL. Framework-neutral. Adopt as house style and keep it consistent across every endpoint.

## Status-code map — when each

| Code | Meaning | Use when |
|---|---|---|
| 200 OK | success + body | GET, or a PUT/PATCH that returns the updated resource |
| 201 Created | created | POST created a resource — include `Location: /collection/{id}` |
| 202 Accepted | accepted, not done | async work queued — return a status/poll URL |
| 204 No Content | success, no body | DELETE, or PUT/PATCH that returns nothing |
| 304 Not Modified | cache hit | conditional GET with `If-None-Match` and ETag matched |
| 400 Bad Request | malformed | body/params unparseable or syntactically wrong |
| 401 Unauthorized | unauthenticated | missing/invalid credentials — re-auth may help |
| 403 Forbidden | unauthorized | authenticated but lacks permission/scope |
| 404 Not Found | absent | resource doesn't exist (or is hidden from this caller) |
| 405 Method Not Allowed | wrong verb | path exists, method doesn't — set `Allow` header |
| 409 Conflict | state collision | duplicate, version mismatch, concurrent edit |
| 412 Precondition Failed | stale write | `If-Match` ETag no longer matches |
| 415 Unsupported Media Type | bad content-type | server can't process the sent representation |
| 422 Unprocessable Content | semantic invalid | parses fine, fails business validation |
| 429 Too Many Requests | rate limited | include `Retry-After` |
| 500 Internal Server Error | server fault | unexpected — never leak the stack |
| 503 Service Unavailable | temporarily down | maintenance/overload — `Retry-After` if known |

Rule of thumb: client mistakes are 4xx, server faults are 5xx. Never blame the client for your bug, never hide your bug behind a 200.

## Query grammar (filter / sort / sparse fieldsets)

Keep one grammar across all list endpoints so clients learn it once.

```http
GET /projects?status=active&owner=u_42&sort=-created_at,title&fields=id,title,status&limit=50
```

- **Filter** by field name as a query key: `?status=active`. For operators, namespace them: `?created_at[gte]=2026-01-01`. Pick one operator syntax and never mix.
- **Sort** with a comma list; `-` prefix = descending: `?sort=-created_at,title`.
- **Sparse fieldsets** let clients trim payloads: `?fields=id,title`. Whitelist allowed fields server-side.
- **Reserve** `limit`, `cursor` (or `offset`), `sort`, `fields`, `q` (free-text search) so they never collide with resource fields.

## Content negotiation

- Default to `application/json`. Honor `Accept`; return `406 Not Acceptable` if you can't satisfy it.
- Validate `Content-Type` on writes; `415` if unsupported.
- Version via media type only if you chose header versioning (see versioning reference); otherwise keep it simple.

## Rate-limit headers

Expose limits so well-behaved clients self-throttle:

```http
RateLimit-Limit: 1000
RateLimit-Remaining: 12
RateLimit-Reset: 1735689600
Retry-After: 30
```

On 429 always send `Retry-After`. Prefer the IETF `RateLimit-*` fields; the older `X-RateLimit-*` names are still common in the wild.

## HATEOAS — pragmatic stance

Full hypermedia (links driving all client navigation) is rarely worth it for typical JSON APIs; clients hardcode URLs anyway. Useful subset: include a `Location` on 201, a `Link` header for pagination/successor-version, and self/next links in list envelopes when it costs little. Don't build a hypermedia framework no client will follow.

# Versioning & evolution

Default posture: **evolve additively, version rarely.** A version is a fork of your client base — earn it.

## Breaking vs non-breaking matrix

| Change | Breaking? | Notes |
|---|---|---|
| Add a new optional response field | No | clients ignore unknown fields if you told them to |
| Add a new endpoint | No | nothing existing changes |
| Add a new optional query/body param | No | old requests still valid |
| Add a new enum value | No* | *only if clients were told to tolerate unknown values; otherwise breaking |
| Loosen a validation rule | No | previously-rejected input now accepted |
| Remove or rename a field | **Yes** | clients reading it break |
| Change a field's type or format | **Yes** | `string` → `object`, date format change, etc. |
| Make an optional field required | **Yes** | old requests start failing |
| Tighten validation (narrower accepted range) | **Yes** | previously-valid input now rejected |
| Change a status code for a case | **Yes** | client branching breaks |
| Change an error `type` URI for a case | **Yes** | clients branch on `type` |
| Change pagination/cursor semantics | **Yes** | in-flight pagination breaks |

Design hint: tell clients up front to **ignore unknown fields and tolerate unknown enum values** ("must-ignore" / robustness rule). That single contract clause turns many would-be breaking changes into additive ones.

## Three versioning mechanisms

| Mechanism | Example | Pros | Cons |
|---|---|---|---|
| **URL path** | `/v1/projects` | visible, cacheable, browser-testable, expected by most clients | version leaks into every URL; "v" is coarse-grained |
| **Header / media type** | `Accept: application/vnd.acme.v2+json` | clean URLs, content-negotiated | harder to test/cache, easy to forget, opaque to humans |
| **Query param** | `/projects?version=2` | trivial to add | pollutes URLs, easy to omit, muddies caching |

**Default to URL path for public APIs.** Reserve header/media-type versioning for internal APIs where tooling controls the header. Don't mix mechanisms.

## Deprecation & sunset workflow

1. Ship the successor (new field/endpoint/version) additively.
2. Mark the old surface deprecated in responses:

```http
Deprecation: true
Sunset: Sat, 31 Oct 2026 23:59:59 GMT
Link: <https://api.acme.com/v2/projects>; rel="successor-version"
```

3. Document the migration and the sunset date; notify known integrators.
4. Hold the deprecated surface working until the `Sunset` date — give clients real time (months, not days, for public APIs).
5. After sunset, return `410 Gone` for the removed surface (not `404`) so clients learn it was intentional.

Keep the deprecation window generous and the messaging programmatic — clients should learn from headers, not from breakage.

#!/usr/bin/env bash
# verify.sh — read-only check of an API-design artifact (OpenAPI 3.1 spec).
#
# The api-design skill emits its contract as an OpenAPI document. This script
# finds candidate spec files under a target dir, validates they parse and carry
# the required OpenAPI keys, and emits non-fatal warnings for the design
# anti-patterns it can detect statically. It never writes anything.
#
# Usage:   verify.sh [TARGET_DIR]   (default: current directory)
# Exit:    0  no spec found (soft-pass) OR all found specs valid
#          1  a spec file is present but invalid/unparseable
#
# Soft-pass on a clean/empty target: a design may live only in a doc.

set -uo pipefail

TARGET="${1:-.}"
fail=0

note()  { printf '  - %s\n' "$1"; }
warn()  { printf '  ! %s\n' "$1"; }

if [ ! -d "$TARGET" ]; then
  echo "verify(api-design): target '$TARGET' is not a directory — nothing to check."
  exit 0
fi

# Collect candidate OpenAPI files (read-only). Tolerate no matches.
# Portable to bash 3.2 (macOS default): no mapfile; newline-delimited list.
specs=()
while IFS= read -r f; do
  [ -n "$f" ] && specs+=("$f")
done < <(
  find "$TARGET" \
    \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' \
       -o -name '*.openapi.yaml' -o -name '*.openapi.yml' -o -name '*.openapi.json' \) \
    -type f 2>/dev/null
)

if [ "${#specs[@]}" -eq 0 ]; then
  echo "verify(api-design): no OpenAPI spec found under '$TARGET' — soft-pass (design may be in-doc only)."
  exit 0
fi

# Choose a linter if available; else fall back to a structural check.
LINTER=""
if command -v redocly >/dev/null 2>&1; then
  LINTER="redocly"
elif command -v spectral >/dev/null 2>&1; then
  LINTER="spectral"
fi

# Structural fallback: parse + required keys, using whatever is on PATH.
parse_check() {
  local f="$1"
  case "$f" in
    *.json)
      if command -v jq >/dev/null 2>&1; then
        jq -e 'has("openapi") and has("info") and has("paths")' "$f" >/dev/null 2>&1
        return $?
      fi
      ;;
    *.yaml|*.yml)
      if command -v python3 >/dev/null 2>&1; then
        python3 - "$f" <<'PY' >/dev/null 2>&1
import sys
try:
    import yaml
except Exception:
    sys.exit(2)  # no yaml lib -> can't check, treat as inconclusive
with open(sys.argv[1]) as fh:
    d = yaml.safe_load(fh)
sys.exit(0 if isinstance(d, dict) and all(k in d for k in ("openapi", "info", "paths")) else 1)
PY
        local rc=$?
        [ "$rc" -eq 2 ] && return 3   # inconclusive
        return $rc
      fi
      ;;
  esac
  return 3  # inconclusive: no suitable parser on PATH
}

# Static anti-pattern warnings (grep-based, never fatal).
antipattern_scan() {
  local f="$1"
  if grep -Eiq '"?/[A-Za-z0-9_]*(get|create|update|delete|fetch|list)[A-Za-z0-9_]*"?[[:space:]]*:' "$f"; then
    warn "verb-like path segment(s) detected — paths should be nouns; HTTP methods are the verbs."
  fi
  if grep -Eq '(/[A-Za-z0-9_/{}]*)+[[:space:]]*:' "$f" && ! grep -Eiq 'cursor|limit|offset|first|after|page' "$f"; then
    warn "no pagination params (cursor/limit/offset) found — list endpoints should paginate."
  fi
  if ! grep -Eiq 'problem\+json|"4[0-9][0-9]"|default[[:space:]]*:' "$f"; then
    warn "no 4xx / default error responses found — every operation should define an error response (RFC 9457)."
  fi
}

echo "verify(api-design): checking ${#specs[@]} spec file(s) under '$TARGET'"
[ -n "$LINTER" ] && echo "  using linter: $LINTER"

for f in "${specs[@]}"; do
  echo "* $f"
  ok=1
  if [ -n "$LINTER" ]; then
    if [ "$LINTER" = "redocly" ]; then
      redocly lint "$f" >/dev/null 2>&1 || ok=0
    else
      spectral lint "$f" >/dev/null 2>&1 || ok=0
    fi
    if [ "$ok" -eq 0 ]; then
      # Linter unhappy: confirm with structural parse before failing hard.
      parse_check "$f"; pc=$?
      if [ "$pc" -eq 0 ]; then
        warn "$LINTER reported issues but the spec parses and has required keys — review lint output."
      else
        note "spec is invalid per $LINTER."
        fail=1
        continue
      fi
    fi
  else
    parse_check "$f"; pc=$?
    case "$pc" in
      0) : ;;  # valid
      3) warn "no parser on PATH (jq/python3+pyyaml) — skipped structural validation." ;;
      *) note "spec does not parse or is missing required keys (openapi/info/paths)."; fail=1; continue ;;
    esac
  fi
  antipattern_scan "$f"
done

if [ "$fail" -ne 0 ]; then
  echo "verify(api-design): FAIL — one or more specs are invalid."
  exit 1
fi

echo "verify(api-design): OK (warnings, if any, are advisory)."
exit 0