ericrisco/rsc-harness / skills/api-design
api-design
VerifiedUse 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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.1 KB |
| evals/README.md | markdown | 518 B |
| evals/cases.yaml | config | 3.1 KB |
| references/graphql-design.md | markdown | 2.9 KB |
| references/openapi-contract.md | markdown | 3.2 KB |
| references/rest-conventions.md | markdown | 3.4 KB |
| references/versioning-and-evolution.md | markdown | 2.7 KB |
| scripts/verify.shexecutable | script | 4.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |