Skip to content

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

api-contracts

Verified

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.

FileKindSize
SKILL.mdskill md2.6 KB
capability.jsonconfig2.2 KB
---
name: api-contracts
description: >-
  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.
license: MIT
---

# 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: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall