Skip to content

AL-JANEF/janef-forge / skills/engineering/api-contracts

api-contracts

Unverified

Design and change REST, GraphQL, RPC, and webhook contracts and the backend services and jobs behind them: validation, authorization scope, error semantics, pagination, idempotency, rate limits, retries, timeouts, versioning, and contract tests. Use for any endpoint, external integration, worker, or queue consumer.

API Contracts & Backend Services

Every external request and every upstream response is untrusted. A contract is a promise to callers you may never see; change it deliberately or not at all.

Contract

  • Specify input validation, authentication, authorization scope (object and tenant), response shape, status and error semantics, timeouts, and observability for every endpoint.
  • Bound request bodies, pagination, retries, concurrency, and external response sizes. Explicit pagination for every unbounded collection.
  • Idempotency for retriable side effects. Rate limits and retry/backoff where abuse or downstream saturation is plausible.
  • Keep transport parsing separate from domain decisions and infrastructure adapters.
  • Never break a contract silently: version or stage the change, then update callers, docs, and tests together.
  • Error responses are useful to the caller without leaking stack traces, internal identifiers, or sensitive implementation detail.

Webhooks and external integrations

Verify authenticity (signature, timestamp window), resist replay or make processing idempotent, bound processing time, and retry safely. Set timeouts and cancellation on all outbound calls; retry only transient, idempotent operations with jitter and limits.

Reliability

  • Make transaction boundaries and side-effect ordering explicit. When atomicity ends, use an outbox or a compensating action.
  • Design jobs and queue consumers for at-least-once delivery unless the platform proves otherwise; make duplicate handling safe.
  • Preserve error cause and correlation context without exposing internals. Avoid shared mutable process state when multiple workers or restarts are possible.

Verification

  • Contract or integration tests for material changes, exercising the real serialization and persistence boundary, not only mocked domain methods.
  • Test validation failures, unauthorized and forbidden requests, duplicate or retried deliveries, and dependency failure where relevant.
  • Confirm observability can distinguish caller errors, server faults, and dependency failures.

Route to database-integrity when persistence decisions are central and to auth-hardening when the endpoint issues or validates credentials.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall