design-api

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Design

## Desired Outcome

Design the API surface for inter-service and client-facing communication, as specification files that
downstream skills can generate code from and verify code against:

- API style decision — REST, GraphQL, hybrid, gRPC or AsyncAPI per consumer/service surface
- REST API — OpenAPI 3.1 (or 3.0 where a toolchain requires it) specification per service
- GraphQL inventory and handoff to `/architect:design-graphql` when selected
- gRPC protobuf definitions (inter-service communication)
- AsyncAPI (event-driven communication)
- A problem type registry — the enumerable set of error kinds the API can return
- API Gateway design (routing, authentication, rate limiting)

The specification is the **contract**, not an illustration of one. @rules/api-contract-fidelity.md §1
governs the relationship between it and every downstream artifact: code may not exceed it, may not
contradict it, and changing behaviour means changing the specification first.

## Decision Criteria

### Protocol and surface
- Apply @rules/api-style-selection.md. Select protocol from consumer variability, operation shape,
  caching, governance, security and operations — never from service label or database product alone.
- Decide per surface and allow a justified hybrid: flexible reads may use GraphQL while strict
  commands, files and webhooks use REST/gRPC/events.
- Record `access_surface`, `application_framework`, `data_access` and `transaction` separately.
- Write per-surface decisions to canonical machine-readable JSON and generate its Markdown view
  with the plugin validator. For every
  ScalarDB-backed surface include `graphql_provider`, `native_exposure`, `approval`,
  `pinned_product`, `pinned_release`, `contracted_edition`, `control_evidence`, and `rationale` as
  defined by @rules/api-style-selection.md. For exposed native GraphQL, create the separate human
  approval registry at `reports/03_design/api-style-approvals.json`, use project-relative control
  evidence references, and resolve release and edition against the version decision, pinned OKF
  line, and edition-selection report. Missing or fabricated native-interface evidence blocks
  completion, including when progress is recomputed without rerunning this skill.
- The canonical JSON directly controls whether `design-graphql` runs. Do not copy the selection into
  `options.api_style_graphql`; a legacy value may exist, but orchestration ignores it once the
  canonical artifact exists.
- API versioning strategy, and what counts as a breaking change (@rules/api-contract-fidelity.md §8)
- One project-wide convention for pagination, sorting and filtering — decided here, once

### Transaction-shaped operations
The transaction design is an **input**, not a downstream concern. Each operation is placed against it:
- Which operations sit inside one ACID transaction, which participate in a saga, which are local
- For 2PC surfaces, the participant operations (prepare / validate / commit / abort) are contract
  operations like any other and get the same treatment
- Every non-idempotent operation that a client may retry — anything that creates or moves money,
  stock, or state — declares an `Idempotency-Key` obligation (@rules/api-error-standard.md §5)
- A per-operation timeout and retry budget, consistent with the SLOs in `reports/04_quality/sla.md`
  when the product pipeline supplied them

### Authorization
- Authentication scheme per operation (OAuth2/OIDC), and the **authorization rule per operation**:
  the role/scope required, plus the object-level ownership predicate where one applies
- An operation whose authorization is undeclared is read downstream as public. Decide it here — this
  is the input to the BOLA/BFLA review, and the most common source of API vulnerabilities

### Errors
- Error responses are RFC 9457 Problem Details, per @rules/api-error-standard.md. No second error
  envelope anywhere in the project
- The problem type registry is allocated here and every error response references a registered `type`

## Knowledge Grounding

For a ScalarDB project, the transaction mechanism an operation depends on (shared cluster, Global
Transaction API, application-driven 2PC, Saga) is resolved against the project's pinned release per
@rules/okf-knowledge-bundle.md before it is written into the contract — the available mechanisms
differ by version and edition, and an operation designed around one the project cannot run is a
contract that cannot be implemented.

## Contract Verifiability (mandatory)

Every REST operation this skill emits satisfies @rules/api-contract-fidelity.md §3. GraphQL surfaces
must satisfy @rules/graphql-contract-fidelity.md through `/architect:design-graphql`. Restated as the
checklist to apply before writing each specification file:

- [ ] `operationId` on every operation — `camelCase` verb-noun, unique project-wide, naming the
      business action (§2)
- [ ] Every request and response schema is a **named** `components/schemas` entry, never inline
- [ ] Every response status code declared, success **and** error, each with a schema
- [ ] Error responses use `application/problem+json` and a registered `type`
- [ ] Required vs optional decided for every property; `nullable` used deliberately
- [ ] Constraints in the schema (`minLength`, `maximum`, `pattern`, `enum`, `format`) — not in prose
- [ ] At least one success example and one error example per operation
- [ ] `security` declared per operation, with the role/scope and ownership predicate recorded
- [ ] `Idempotency-Key` parameter declared where §5 of the error standard requires it
- [ ] **Every operation with a client-supplied idempotency/replay key** (an `Idempotency-Key`
      header OR a client-generated resource ID whose re-send replays, e.g. a TCC reservation ID)
      declares (a) the **replay-branch authorization**: the ownership predicate evaluated on the
      replay path itself, and the response for a foreign key (404, existence concealment), and
      (b) the **storage table** for the idempotency record, cross-referenced to the schema design
      — a record scoped to the principal, committed in the same transaction as the business
      write. A replay branch with no declared authorization is the §5 BOLA bypass and blocks
      completion (shipped once as ASEC-101/ASEC-102)
- [ ] **`transaction-status-unknown` declared on every service that writes through ScalarDB** —
      each such service's OpenAPI carries the 503 (idempotency-protected) and/or 500
      (unprotected, with the named reconciliation operation) response per
      @rules/api-error-standard.md §3.1. A correct implementation must not exceed its contract

These are not style preferences: each one is what makes a specific downstream check possible.
`generate-api-code` generates DTO names from schema names and Bean Validation from schema
constraints; `generate-contract-tests` uses the examples as fixtures; `verify-implementation` cannot
report a status-code break the contract never declared.

## Open Questions

Where an operation's authorization rule, idempotency obligation, timeout budget, or consistency
placement cannot be resolved from the inputs, ask the user per @rules/open-questions.md rather than
writing a permissive default. A silently-public operation and a silently-unbounded timeout are both
defects that surface much later and much more expensively.

## Prerequisites

| File | Required/Recommended | Source |
|------|---------------------|--------|
| reports/03_design/target-architecture.md | Required | /architect:design-microservices |
| reports/03_design/scalardb-transaction.md | Required when scalardb_enabled | /architect:design-scalardb — which operations sit in one transaction, which are saga steps, which are 2PC participants |
| reports/03_design/data-layer-design.md | Required when scalardb_disabled | /architect:design-data-layer |

From Ryuking1228/ai-dev-codex-version, MIT.

More from Ryuking1228/ai-dev-codex-version