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/versioning-and-evolution.md

View on GitHub
# 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.
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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