graphql

GraphQL

GraphQL's power comes from its type system and client-driven queries. Its most common failure modes come from ignoring what that freedom costs on the server side.

When to Use

• Designing a new GraphQL API or adding types/resolvers to an existing one
• Reviewing resolver code for N+1 problems or missing authorization
• Implementing subscriptions for real-time data
• A GraphQL endpoint is slow and the cause is unknown
• Migrating from REST to GraphQL or running both in parallel

When NOT to Use

• Simple CRUD APIs with no complex data relationships — REST is simpler
• File upload endpoints — use a REST endpoint alongside GraphQL
• Public APIs consumed by third parties who need stable versioning — REST with OpenAPI is clearer

Schema Design

Types

Use specific scalar types — never fall back to String when a purpose-built type exists:

scalar DateTime    # ISO 8601 timestamp
scalar UUID        # UUID string with validation
scalar URL         # Valid URL string
scalar JSON        # Untyped JSON — use sparingly, prefer typed objects

type Document {
  id: UUID!
  title: String!
  content: String!
  tags: [String!]!      # Non-null list of non-null strings
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User!         # Nullable only if the author can be deleted
}

Nullability rules:

• Default to non-null (!) for fields that will always have a value
• Use nullable only when the field genuinely may be absent (optional relationship, lazy-loaded field)
• [String!]! — non-null list of non-null strings (most common for arrays)
• [String] — nullable list of nullable strings (almost never correct)

Naming conventions:

• Types: PascalCase
• Fields and arguments: camelCase
• Enum values: SCREAMING_SNAKE_CASE
• Queries: describe what is returned (document, documents, searchDocuments)
• Mutations: verb + noun (createDocument, updateDocument, deleteDocument)
• Subscriptions: on + event (onDocumentCreated, onCommentAdded)