api-design

name	api-design
description	Design and review REST, OpenAPI, GraphQL, webhook, and internal service APIs. Use for contracts, versioning, idempotency, pagination, errors, auth, and SDK ergonomics.

API Design

Purpose

Create APIs that are predictable for clients, safe for servers, and maintainable over time.

Workflow

1. Identify consumers, use cases, auth model, and backward compatibility needs.
2. Define resources, operations, request/response schemas, error model, and idempotency.
3. Review pagination, filtering, sorting, rate limits, and webhooks.
4. Produce OpenAPI-compatible descriptions when useful.
5. Include migration and deprecation notes for existing APIs.

Output

Return:

• API shape.
• Schema examples.
• Error model.
• Auth and rate-limit notes.
• Compatibility risks.