AL-JANEF/janef-forge / skills/engineering/api-contracts
api-contracts
VerifiedDesign 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.6 KB |
| capability.json | config | 2.2 KB |
SKILL.md
View on GitHub---
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |