Source: https://github.com/aipoch/medical-research-skills

API Design Principles

When to Use

Designing a new REST API contract for CRUD-style resources and you need consistent resource modeling, naming, and HTTP semantics.
Designing a new GraphQL schema for multiple clients with different data shapes and you need clear type/field ownership and safe evolution.
Reviewing an existing API (REST or GraphQL) to identify inconsistencies in naming, error handling, pagination/filtering, or versioning/deprecation.
Deciding between REST vs. GraphQL (or defining boundaries when mixing both) and documenting trade-offs and constraints.
Standardizing cross-cutting concerns (authn/authz, rate limiting, observability, long-running operations, idempotency) across multiple services.

End-to-end workflow for API design/review: requirements → style choice → domain modeling → operations → cross-cutting concerns → deliverables.
REST guidance: resource-oriented modeling, stable identifiers, relationship patterns, and correct HTTP verb usage.
GraphQL guidance: schema/type modeling, Query vs. Mutation separation, input types for writes, and explicit side-effect handling.
Cross-cutting design patterns: consistent error model, pagination/filtering/sorting, versioning and deprecation strategy, and operational concerns.
Review checklist to validate completeness, highlight risks/gaps, and produce actionable follow-ups.