domains / software-engineering / api-design-review / api-design-principles

api-design-principles

Skill card

combined

The copies overlap on the high-level workflow (define consumers, choose style, model resources, specify errors/versioning/pagination/auth, validate), but they disagree on the level of detail and the concrete artifacts. rmyndharis and sickn33 are nearly identical short procedures that point to a missing `resources/implementation-playbook.md`. LeoYeAI provides a detailed, code-heavy implementation guide with Python/FastAPI examples for pagination, error handling, and HATEOAS. aipoch provides a different, more rigorous workflow focused on contract design, idempotency, and a specific review checklist with `curl` examples. Crowning one would hide the specific implementation patterns in LeoYeAI or the rigorous contract-review workflow in aipoch.

Repositories

Other copies

Combined skill

---
name: api-design-principles
description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs. Use when designing new APIs, reviewing specifications, or establishing standards.
---

# API Design Principles

## When to Use
- Designing new REST or GraphQL APIs.
- Refactoring existing APIs for better usability.
- Establishing API design standards.
- Reviewing API specifications before implementation.

## Instructions

1. **Define Consumers and Constraints**
   - Identify consumer types (web, mobile, partners, internal).
   - Capture constraints: latency, throughput, consistency, compliance, and data sensitivity.

2. **Choose API Style and Boundaries**
   - **REST**: Best for resource-oriented CRUD, cacheable reads, and simple endpoints.
   - **GraphQL**: Best for multiple clients with varying data shapes and frequent iteration.
   - If mixing, define clear boundaries (e.g., GraphQL for read aggregation, REST for writes).

3. **Model Resources and Types**
   - **REST**: Use nouns for resources, stable identifiers, and consistent naming. Map operations to HTTP verbs (GET, POST, PUT, PATCH, DELETE).
   - **GraphQL**: Define types and field ownership. Use Query for reads, Mutation for writes, and Input types for complex arguments.

4. **Specify Cross-Cutting Concerns**
   - **Errors**: Define a consistent error model (code, message, details, requestId). Use appropriate HTTP status codes.
   - **Pagination**: Choose between offset-based or cursor-based pagination. Define filtering and sorting rules.
   - **Versioning**: Choose a strategy (URL, Header, or Query Parameter) and define a deprecation plan.
   - **Auth & Security**: Define authentication (e.g., Bearer tokens) and authorization scopes. Consider idempotency keys for write operations.

5. **Validate and Review**
   - Create request/response examples (e.g., using `curl` or code snippets).
   - Review for consistency in naming, error handling, and pagination.
   - Check for risks or gaps in the contract.

## Resources
- Refer to specific implementation playbooks or checklists for detailed patterns if available in the local context.