principle-api-design

What problem does it solve?

This Skill prevents API breakage and integration pain by enforcing contract-first thinking, stable versioning, safe retries, consistent errors, and long-term evolvability.

Core Features & Use Cases

• Contract-first API design: defines resource modeling and error cases up front to reduce downstream ambiguity.
• Production-grade API discipline: covers semantic versioning, deprecation windows, and backward/forward compatibility rules.
• Reliability & usability patterns: specifies idempotency keys for non-idempotent operations, safe pagination strategies, and consistent error envelopes (including request correlation).
• Architecture trade-off guidance: helps choose REST vs RPC vs event-driven approaches based on client ecosystem, latency, typing, streaming, and consistency needs.
• Pragmatic guardrails: highlights red flags like unsafe HTTP semantics, version creep, schema leakage, and inconsistent error responses.

Quick Start

Ask the API-focused assistant to review your endpoint design and propose a versioning, idempotency, pagination, and error-shape plan that preserves backward compatibility.