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/rest-conventions.md
View on GitHub# REST conventions
Depth behind the SKILL. Framework-neutral. Adopt as house style and keep it consistent across every endpoint.
## Status-code map — when each
| Code | Meaning | Use when |
|---|---|---|
| 200 OK | success + body | GET, or a PUT/PATCH that returns the updated resource |
| 201 Created | created | POST created a resource — include `Location: /collection/{id}` |
| 202 Accepted | accepted, not done | async work queued — return a status/poll URL |
| 204 No Content | success, no body | DELETE, or PUT/PATCH that returns nothing |
| 304 Not Modified | cache hit | conditional GET with `If-None-Match` and ETag matched |
| 400 Bad Request | malformed | body/params unparseable or syntactically wrong |
| 401 Unauthorized | unauthenticated | missing/invalid credentials — re-auth may help |
| 403 Forbidden | unauthorized | authenticated but lacks permission/scope |
| 404 Not Found | absent | resource doesn't exist (or is hidden from this caller) |
| 405 Method Not Allowed | wrong verb | path exists, method doesn't — set `Allow` header |
| 409 Conflict | state collision | duplicate, version mismatch, concurrent edit |
| 412 Precondition Failed | stale write | `If-Match` ETag no longer matches |
| 415 Unsupported Media Type | bad content-type | server can't process the sent representation |
| 422 Unprocessable Content | semantic invalid | parses fine, fails business validation |
| 429 Too Many Requests | rate limited | include `Retry-After` |
| 500 Internal Server Error | server fault | unexpected — never leak the stack |
| 503 Service Unavailable | temporarily down | maintenance/overload — `Retry-After` if known |
Rule of thumb: client mistakes are 4xx, server faults are 5xx. Never blame the client for your bug, never hide your bug behind a 200.
## Query grammar (filter / sort / sparse fieldsets)
Keep one grammar across all list endpoints so clients learn it once.
```http
GET /projects?status=active&owner=u_42&sort=-created_at,title&fields=id,title,status&limit=50
```
- **Filter** by field name as a query key: `?status=active`. For operators, namespace them: `?created_at[gte]=2026-01-01`. Pick one operator syntax and never mix.
- **Sort** with a comma list; `-` prefix = descending: `?sort=-created_at,title`.
- **Sparse fieldsets** let clients trim payloads: `?fields=id,title`. Whitelist allowed fields server-side.
- **Reserve** `limit`, `cursor` (or `offset`), `sort`, `fields`, `q` (free-text search) so they never collide with resource fields.
## Content negotiation
- Default to `application/json`. Honor `Accept`; return `406 Not Acceptable` if you can't satisfy it.
- Validate `Content-Type` on writes; `415` if unsupported.
- Version via media type only if you chose header versioning (see versioning reference); otherwise keep it simple.
## Rate-limit headers
Expose limits so well-behaved clients self-throttle:
```http
RateLimit-Limit: 1000
RateLimit-Remaining: 12
RateLimit-Reset: 1735689600
Retry-After: 30
```
On 429 always send `Retry-After`. Prefer the IETF `RateLimit-*` fields; the older `X-RateLimit-*` names are still common in the wild.
## HATEOAS — pragmatic stance
Full hypermedia (links driving all client navigation) is rarely worth it for typical JSON APIs; clients hardcode URLs anyway. Useful subset: include a `Location` on 201, a `Link` header for pagination/successor-version, and self/next links in list envelopes when it costs little. Don't build a hypermedia framework no client will follow.
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: 471k | 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: 471k | 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: 471k | 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 |