← Back

API Design

The schema is the contract. Design for how consumers need data, not how the database stores it. Start minimal. Expand as needed.

When to Use What

  • GraphQL for client-facing APIs with multiple consumers (web, mobile, partners). Single endpoint, unified data catalog, central access control.
  • REST for workers, MCP servers, or simple services where GraphQL adds unnecessary overhead.
  • tRPC for internal TypeScript monorepo services. End-to-end type safety without schema generation.

Demand-Oriented Schema Design

Include only fields clients need. Move business logic — language detection, formatting, computed fields — to the backend. Each platform should not duplicate logic that belongs in one place.

  • Design types for use cases, not database tables. Remove internal fields (created_at, country_id).
  • Use Enum types instead of raw strings.
  • If the client always displays a combined value, provide it as a single field (e.g., displayPrice instead of price + currency).
  • Data that is always displayed together should live together.

Queries

  • No get prefix — it is redundant. Use productById, productBySlug.
  • Specific queries over generic filters. Each query serves one purpose.
  • Never combine multiple lookups into one query with optional parameters.
  • Return type: capitalized query name with Payload postfix.

Mutations

  • Name mutations after actions, not CRUD. signUp over createUser.
  • Each mutation handles one use case. Split fat mutations. updateUserPreferredLocale, updateUserPreferredCurrency — not a generic updateUser.
  • Single input argument with Input postfix. Return type with Payload postfix.

Naming Conventions

  • Queries, mutations, fields: camelCase
  • Types, enums, inputs: PascalCase
  • Enum values: ALL_CAPS
  • No get prefix on queries
  • Offset pagination for pages, cursor pagination for infinite scroll

Schema-First vs Code-First

  • TypeScript projects: code-first (TypeGraphQL, Nexus) eliminates schema-resolver inconsistencies and gives automatic typing.
  • JavaScript projects: schema-first is simpler and separates concerns better.
  • Prerequisite for code-first: understand GraphQL well, since the schema auto-generates.

Collaborate Before Building

Ask for the Figma. Understand how clients plan to use the data before designing the endpoint. Client teams should approve the schema before implementation. Discuss changes on PRs — creates discussion history and recorded approval.

Never share types between public and private schemas. Duplicate queries, mutations, and types if needed. Sharing can expose data and prevent schemas from evolving independently.

Evolution

  • Feb 2026 — rewritten in rule-oriented format from GraphQL articles, IDENTITY.md, and code review patterns.