API Design First

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Design APIs as contracts before code. This skill produces the OpenAPI 3.1 contract and its companion auth / error / idempotency / observability artifacts that downstream frontend, mobile, SDK, security, and reliability skills depend on.

Use When

• Designing a new HTTP API (REST or GraphQL decision open), or adding endpoints to an existing API.
• Normalising an existing API against the house contract (envelope, error model, versioning, rate limits).
• Producing the OpenAPI contract that SDK, frontend, mobile, contract-testing, and security skills will consume.
• Choosing an auth method and writing the auth/role matrix for a new service.
• Defining idempotency keys and observability notes handed to reliability-engineering and observability-monitoring.

Do Not Use When

• The task is purely client-side consumption of a third-party API (load the relevant SDK or integration skill).
• The task is full threat modelling — load vibe-security-skill; this skill only records the auth model.
• GraphQL-specific hardening is needed — load graphql-patterns.