Skip to content

ericrisco/rsc-harness / skills/api-design

api-design

Verified

Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL, versioning, one RFC 9457 error envelope, pagination, idempotency — emitted as OpenAPI 3.1. NOT implementing the endpoints (that is `fastapi`/`nestjs`/`go`/`nodejs`), NOT auth hardening (that is `security-audit`), NOT consuming a third-party API (that is `api-connector-builder`).

FileKindSize
SKILL.mdskill md12.1 KB
evals/README.mdmarkdown518 B
evals/cases.yamlconfig3.1 KB
references/graphql-design.mdmarkdown2.9 KB
references/openapi-contract.mdmarkdown3.2 KB
references/rest-conventions.mdmarkdown3.4 KB
references/versioning-and-evolution.mdmarkdown2.7 KB
scripts/verify.shexecutablescript4.4 KB

references/openapi-contract.md

View on GitHub
# 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.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall