API Design Standards

API Design Standards

Four categories of API house rules, written as enforceable review standards — each page ends in checks a reviewer can apply to a diff, not vibes.

What's inside

• 🧭 REST Conventions (enforce) — "Resource naming and HTTP semantics": plural-noun paths, no verbs, method and status-code discipline, idempotency rules.
• 🚨 Error Contract (enforce) — "One error shape everywhere": a single machine-readable envelope, the 400-vs-422 house rule, messages that never leak internals.
• 🧬 Versioning & Compatibility (follow) — "Versioning and compatibility rules": additive-first evolution, never repurpose a field, tolerant readers, what actually justifies a /v2.
• 📄 Pagination & Filtering (follow) — "Pagination, filtering, and sorting": one list envelope (items/total/page/page_size), capped page sizes, stable sorts, filter params named after fields.

What install does

Adds these categories and pages to your project. Safe to run twice: Reinstall restores anything missing and never overwrites your edits. No jelly bindings included (jellies are the AI agents inside a crew) — the rules start being enforced only once you bind these categories to your jellies.

What to customize

• Bind REST Conventions and Error Contract to your architecture and QA jellies — Keel and Sonar from the Fullstack Dev Crew are the natural pair; those two categories are enforce for a reason.
• The pagination envelope mirrors this marketplace's own catalog API; if your house shape differs (cursors, offsets), edit that page first so the standard matches reality.
• Add per-service pages for exceptions — a documented exception beats a silently violated rule.