GraphQL Client Vocabulary

An operation is the unit of execution in GraphQL — every client request is an operation.

The three operation types:
• query — read data (safe, cacheable)
• mutation — write data (side effects)
• subscription — receive real-time push events

Named vs anonymous operations:

# Anonymous — avoid in production
{ user(id: "123") { name } }

# Named — the standard in production codebases
query GetUserProfile($userId: ID!) {
  user(id: $userId) { name email avatar }
}

mutation UpdateUserEmail($userId: ID!, $email: String!) {
  updateUser(id: $userId, email: $email) { id email }
}

Why naming matters:
• Operations appear by name in APM tools (Datadog, New Relic, Apollo Studio)
• GetUserProfile in your logs immediately tells you which query is slow — anonymous tells you nothing
• Per-operation metrics: cost, latency, error rate — only possible with named operations
• Persisted queries (sending only the operation name, not the full query document) require named operations
• Client-side debugging: React DevTools, Apollo Client DevTools, Relay show operations by name

Convention: name queries with a noun phrase (GetUserProfile) and mutations with a verb phrase (UpdateUserEmail, DeletePost).

Key vocabulary:
• Operation — a single GraphQL request (query, mutation, or subscription)
• Operation name — the optional identifier after the operation keyword (query GetUserProfile)
• Anonymous operation — an operation without a name; discouraged in production

Fragments are the primary tool for reuse and composition in GraphQL client code.

Two types of fragments:

1. Named fragments — defined separately, reused across operations:

fragment UserCard on User {
  id
  name
  avatarUrl
}

query GetTeamMembers {
  team { members { ...UserCard } }
}

query GetAuthor {
  post(id: "1") { author { ...UserCard } }
}

2. Inline fragments — for conditional fields on union or interface types:

query GetSearchResults {
  search(query: "GraphQL") {
    ... on Article { title author }
    ... on Video { title duration thumbnailUrl }
    ... on User { name email }
  }
}

Co-location pattern (Relay/Apollo):
Each React/Vue/Svelte component defines a fragment for its own data needs. The root query composes these. Components never "over-request" or "under-request" data:

// UserAvatar.tsx
const USER_AVATAR_FRAGMENT = gql`
  fragment UserAvatar on User { id avatarUrl name }
`;

// ArticleCard.tsx  
const ARTICLE_CARD_FRAGMENT = gql`
  fragment ArticleCard on Article {
    id title publishedAt
    author { ...UserAvatar }
  }
  ${USER_AVATAR_FRAGMENT}
`;

Key vocabulary:
• Fragment — a named, reusable selection set defined with fragment Name on Type { ... }
• Fragment spread — the ...FragmentName syntax used to include a fragment in a query
• Inline fragment — ... on TypeName { fields } used for polymorphic types (unions, interfaces)
• Co-location — the pattern of keeping a component's data requirements in the same file as the component

Variables are the fundamental mechanism for parameterizing GraphQL operations — always use them for dynamic values.

Variables syntax:

# Operation definition with variable declaration
query GetUser($userId: ID!, $includeEmail: Boolean = false) {
  user(id: $userId) {
    name
    email @include(if: $includeEmail)
  }
}

# Variable values sent separately as JSON
{
  "userId": "abc-123",
  "includeEmail": true
}

Reasons to always use variables:

1. Security — prevents injection:
When you interpolate values into query strings (e.g., template literals), you risk query injection. Variables are never concatenated — they travel alongside the query document as separate JSON.

2. Performance — document caching:
The GraphQL server parses, validates, and plans execution of the query document. With variables, the same document is reused across requests (only the variable values change). Inline literals produce a different document string every time, bypassing the cache.

3. Persisted queries:
Persisted queries work by sending only a hash of the query document. This only works if the document is static — meaning variables must carry all dynamic values.

4. TypeScript code generation:
Tools like GraphQL Code Generator produce TypeScript types for variables. GetUserQueryVariables = { userId: string; includeEmail?: boolean } gives you compile-time type safety for your API calls.

5. Tooling support:
GraphiQL, Apollo Explorer, Insomnia all have separate "Variables" panels. Named variables and typed declarations make operations self-documenting.

Key vocabulary:
• Variable — a named, typed placeholder in an operation ($userId: ID!) whose value is passed separately
• Variable declaration — the ($userId: ID!) after the operation name
• Default value — an optional default for a variable ($limit: Int = 10)
• @include / @skip — built-in directives controlled by Boolean variables to conditionally include/exclude fields

Over-fetching and under-fetching are the two fundamental data-fetching inefficiencies that GraphQL was designed to solve.

Over-fetching example:

# REST: GET /users/123
# Returns ALL fields — 40 properties
{
  "id": "123", "name": "Alice", "email": "...", "phone": "...",
  "address": {...}, "billing_info": {...}, "preferences": {...},
  "created_at": "...", "updated_at": "...", ...
}
# Client only needed: { id, name, avatarUrl } — 3 fields
# 37 fields wasted bandwidth, serialize/parse time, memory

Over-fetching impact:
• Wasted bandwidth — especially costly on mobile networks
• JSON serialization/deserialization overhead for unused data
• Mobile data caps and battery drain from unnecessary data transfer

Under-fetching / waterfall requests example:

# REST: Loading a profile page requires:
GET /users/123              # 1. fetch user
GET /users/123/posts        # 2. fetch their posts
GET /posts/456/comments     # 3. fetch comments for each post
GET /users/789              # 4. fetch each commenter's profile
# = waterfall: each request waits for the previous one

GraphQL solves both in one query:

query ProfilePage($userId: ID!) {
  user(id: $userId) {
    name avatarUrl        # only what we need!
    posts(first: 5) {
      title
      comments(first: 3) {
        text
        author { name avatarUrl }  # nested, single round-trip
      }
    }
  }
}

Trade-offs (important for balanced discussions):
• GraphQL shifts complexity to the server (resolver layer must handle arbitrary field selections)
• REST is simpler to cache at CDN level than GraphQL POST requests
• GraphQL's flexibility can create authorization complexity (field-level permissions)

Key vocabulary:
• Over-fetching — receiving more data from an API than the client actually uses
• Under-fetching — an endpoint not returning enough data, requiring additional round-trips
• Waterfall requests — sequential dependent API calls, each waiting for the previous
• Declarative data fetching — the client declares what it needs; the server provides exactly that

Persisted queries eliminate several production concerns by pre-registering allowed operations.

How persisted queries work:

# Standard GraphQL request (full query in body)
POST /graphql
{
  "query": "query GetUser($id: ID!) { user(id: $id) { name email posts { title } } }",
  "variables": { "id": "123" }
}

# Persisted query request (hash only)
POST /graphql
{
  "extensions": {
    "persistedQuery": {
      "version": 1,
      "sha256Hash": "a1b2c3d4e5f6..."  # hash of the query document
    }
  },
  "variables": { "id": "123" }
}

Two patterns:

1. Automatic Persisted Queries (APQ):
• Client sends hash first; if server doesn't have it, server returns error
• Client re-sends with full query; server stores it
• Subsequent requests use only the hash
• Apollo Client supports APQ natively

2. Trusted Documents (strict security mode):
• At build time, all operation documents are extracted and sent to the server
• In production, the server only accepts pre-registered queries
• Unknown queries are rejected — even if syntactically valid
• Prevents attackers from sending arbitrary GraphQL queries to your API

Benefits:
• Security — arbitrary query execution blocked; attackers can't probe schema or execute expensive unmaintained queries
• Performance — smaller HTTP request bodies (hash vs full query text)
• CDN caching — GET requests with query hash + variables can be cached by CDN
• Analytics — every operation is identified by name/hash; perfect observability
• Deprecation safety — you can see exactly which clients still use a query before removing it

Key vocabulary:
• Persisted query — a query document pre-stored on the server, referenced by hash or name
• APQ (Automatic Persisted Queries) — Apollo's two-step protocol for automatic query persistence
• Trusted documents — the strict security variant where only pre-registered queries are accepted
• Query hash — the SHA-256 hash of the full query document used as its identifier