API Design Review skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "API Design Review"
  short_description: "Catch contract mistakes before the first client"
  default_prompt: "$api-design-review Review this OpenAPI spec for our public payments API before we build it"

# Protocol checklists for API design review

Read the section for the protocol under review. Each item is a question to ask of the
contract; a "no" is a candidate finding.

## REST / OpenAPI

### Resources and URLs
- Plural nouns for collections (`/orders`), ids in the path (`/orders/{order_id}`), no
  verbs in paths except for explicit actions modelled as sub-resources
  (`POST /orders/{id}/cancel` is acceptable when cancel is not a plain field update).
- Nesting at most one level deep (`/customers/{id}/orders`); deeper hierarchies become
  filters (`/orders?customer_id=`).
- Path and query parameter casing consistent with the rest of the API (snake_case or
  camelCase, one of them).

### Methods and status codes
- `GET` safe, `PUT` and `DELETE` idempotent, `POST` for create and non-idempotent actions,
  `PATCH` with a documented format (JSON Merge Patch, RFC 7396, is the common choice).
- `201 Created` with `Location` for creates; `202 Accepted` plus an operation resource for
  long-running work; `204` for empty success.
- `400` malformed, `401` unauthenticated, `403` forbidden, `404` not found (also used to
  hide existence from unauthorised callers), `409` conflict, `412` precondition failed
  (stale `If-Match`), `422` validation error, `429` with `Retry-After`.
- Every operation declares its error responses in the spec, not only `200`.

### Errors
- One error schema, ideally RFC 9457 `application/problem+json`: `type`, `title`,
  `status`, `detail`, `instance`, plus extension members such as `errors` for field-level
  validation (`[{ "field": "email", "code": "invalid_format" }]`).
- Stable machine-readable codes clients can switch on; human text may change.

### Collections
- Cursor pagination (`limit`, `cursor`/`next_cursor`) by default; offset only for small,
  stable admin lists.
- Documented default and maximum page size; deterministic sort with a tie-breaker.
- Filtering and sorting parameters named consistently across list endpoints.
- Total counts optional (expensive on large tables); do not promise them by default.

### Writes
- `Idempotency-Key` header on creating POSTs that cause side effects; behaviour on key
  reuse with a different body defined (`422` or `409`).
- Optimistic concurrency: `ETag` on reads, `If-Match` required on updates of contended
  resources.
- Server-generated fields (`id`, `created_at`) marked `readOnly`; secrets `writeOnly`.

### Data formats
- Timestamps RFC 3339 in UTC (`2026-10-28T14:03:00Z`); dates as `YYYY-MM-DD`.
- Money as integer minor units plus ISO 4217 currency, or a decimal string; never float.
- Enums documented as extensible if they may grow.
- `nullable` versus absent semantics defined, especially for PATCH.

### Spec hygiene
- `operationId` unique and stable (code generators use it).
- Reusable schemas in `components`; no anonymous inline duplicates.
- Examples for every request and response body.
- `securitySchemes` defined and applied per operation with scopes.

## GraphQL

### Schema shape
- Types model the domain, not database tables; no `userId: ID` without a `user: User`
  field to navigate.
- Nullability chosen deliberately: fields that can fail independently (from other
  services) are nullable so one failure does not null the whole parent; ids and
  invariants are non-null.
- Lists of objects use connections (`edges`, `node`, `pageInfo`, cursor arguments
  `first`/`after`) or a consistent simpler pagination pattern; never unbounded lists of
  growing data.
- Global object identification (`Node` interface, `node(id:)`) if clients cache
  normalised data (Relay, Apollo).

### Mutations
- One input object argument (`input: CreateOrderInput!`) and a payload type
  (`CreateOrderPayload`) rather than returning the bare object, so fields such as
  `userErrors` can be added later.
- Expected business errors returned in the payload (`userErrors { field code message }`)
  or as union result types; transport errors in the `errors` array.
- Idempotency for side-effecting mutations (client mutation id or idempotency key input).

### Evolution
- Deprecate with `@deprecated(reason: "Use totalPrice; removal after 2027-03-01")`
  before removing; track field usage from operation logs.
- New arguments are optional or have defaults.
- Adding enum values and union members can break exhaustive client code; announce them.

### Safety and performance
- Query depth and complexity limits, and persisted or trusted operations for public
  first-party clients.
- Resolvers batched (DataLoader or equivalent); the schema review should flag fields
  that imply N+1 lookups at list scale.
- Field-level authorization for sensitive fields; introspection policy decided for
  production.

## gRPC / Protocol Buffers

### Messages
- Field numbers never reused; removed fields go into `reserved` (both number and name).
- Field types never changed in place; add a new field instead.
- Each RPC has its own request and response message (`GetOrderRequest`,
  `GetOrderResponse`), even if they start with one field, so they can grow.
- Enums start with a `*_UNSPECIFIED = 0` value; values prefixed with the enum name.
- Use well-known types: `google.protobuf.Timestamp`, `Duration`, `FieldMask` for partial
  updates, wrapper types or `optional` when presence matters.
- Money via a type with units and currency (for example `google.type.Money`), not floats.

### Services and methods
- Method names are verbs plus resource (`CreateOrder`, `ListOrders`); standard methods
  follow Google AIP conventions if the team uses them (`List` with `page_size`,
  `page_token`, `next_page_token`).
- Streaming chosen deliberately; server streaming for feeds, not as a substitute for
  pagination of finite lists.
- Long-running work returns an operation (`google.longrunning.Operation`) or an id to poll.
- Deadlines expected on every call; document reasonable values per method.

### Errors
- Canonical status codes used correctly: `INVALID_ARGUMENT` (bad input),
  `FAILED_PRECONDITION` (state does not allow it), `NOT_FOUND`, `ALREADY_EXISTS`,
  `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED` (quota),
  `UNAVAILABLE` (retryable).
- Rich error details (`google.rpc.BadRequest`, `ErrorInfo`) for field-level problems.
- Retry policy documented: which codes are safe to retry for which methods.

### Packaging and tooling
- Package names versioned (`acme.orders.v1`); breaking changes go to `v2` packages.
- `buf lint` with the team's rule set (`STANDARD` is a sensible default) and
  `buf breaking` against the main branch in CI.
- JSON transcoding (gRPC-Gateway, Envoy) considered: field names map to lowerCamelCase
  JSON; check that this matches public REST conventions if exposed.