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

evals/cases.yaml

View on GitHub
skill: api-design

should_trigger:
  - prompt: "Design the REST API for a multi-tenant invoicing service"
    why: core greenfield contract-design request; resource modeling + URLs.
  - prompt: "How do I add a field and a new status value to this endpoint without breaking existing clients?"
    why: evolution/versioning; non-obvious — no words 'API' or 'design', it's the additive-non-breaking rule.
  - prompt: "Should this be REST or GraphQL, and how should pagination work?"
    why: paradigm choice plus pagination convention — both are design-time decisions.
  - prompt: "What's the standard error format? I keep returning a different shape per endpoint"
    why: symptom-led; routes to the single RFC 9457 problem-details envelope.
  - prompt: "Our list endpoint times out at page 5000 with offset pagination"
    why: non-obvious symptom — the fix is a cursor/keyset pagination design, not a query tweak.
  - prompt: "diseña los endpoints y el versionado de nuestra API pública"
    why: Spanish trigger for endpoint design + versioning strategy.
  - prompt: "We need an Idempotency-Key on POST so retries don't double-charge — how should the contract handle it?"
    why: non-obvious header-level contract decision (idempotency), design-time not implementation.

should_not_trigger:
  - prompt: "Implement these endpoints in FastAPI with Pydantic models and async routes"
    route_to: fastapi
    why: build-time framework implementation, not contract design.
  - prompt: "Threat-model this endpoint and check the CORS and CSP config for OWASP issues"
    route_to: security-audit
    why: security/hardening lens, not the API shape.
  - prompt: "Verify the incoming Stripe webhook signature and dedupe replayed events"
    route_to: webhooks
    why: receiving inbound events with HMAC verification, not designing an exposed API.
  - prompt: "Write a client that calls the OpenWeather API and handles its rate limits and retries"
    route_to: api-connector-builder
    why: building an outbound client to a third-party API, not designing one.
  - prompt: "Wire a custom provider with useFactory in my NestJS module"
    route_to: nestjs
    why: framework dependency-injection wiring, not contract design.

capability:
  - scenario: "Design the public REST API contract for a 'projects' resource with nested tasks, supporting pagination, consistent errors, and a versioning plan."
    must_include:
      - plural noun collections and nested path `/projects/{id}/tasks` with no verbs in paths
      - correct methods + status codes, including 201 + Location on create and the 409-vs-422 distinction
      - one RFC 9457 `application/problem+json` error envelope used across all endpoints, with a stable machine `type` and a correlation id, no leaked internals
      - cursor (keyset) pagination with a consistent response envelope (data + next_cursor/has_more)
      - URL-path versioning for the public API plus the additive-non-breaking evolution rule (and Deprecation/Sunset on removal)
      - a handoff note pointing to a framework skill (fastapi/nestjs/go/nodejs) to implement it
      - bonus: an OpenAPI 3.1 sketch of the contract
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