GraphQLgraphqlschemaapi-designtypesproduction-ready

GraphQL Schema Design

Production GraphQL schema with union types, interfaces, pagination, input validation, custom directives, and error handling.


title: "GraphQL Schema Design" description: "Production GraphQL schema with union types, interfaces, pagination, input validation, custom directives, and error handling." category: "GraphQL" language: "graphql" tags: ["graphql", "schema", "api-design", "types", "production-ready"] createdAt: "2025-02-25" updatedAt: "2025-03-15"

Overview

A production GraphQL schema demonstrating best practices: Relay-style cursor pagination, union types for polymorphic results, interfaces for shared fields, structured error types, custom directives for auth/rate-limiting, and the viewer pattern.

Code

type Query {
  viewer: User @auth(requires: USER)
  posts(first: Int, after: String): PostConnection!
  search(query: String!): [SearchResult!]!
}

Notes

  • Relay cursor pagination scales better than offset pagination for large datasets
  • Union types (SearchResult) model polymorphic responses without type casting
  • Structured errors (UserError with code and field) enable programmatic error handling
  • The viewer pattern (Query.viewer) avoids passing user ID for authenticated operations
  • Custom directives (@auth, @rateLimit) keep business logic out of resolvers
  • Always use input types for mutations (enables validation and versioning)