Documenting GraphQL APIs: Queries, Mutations, Schema Directives, and SDL Architecture

While traditional REST APIs center around fixed endpoints and HTTP methods, GraphQL introduces a fundamentally different architectural model: a single unified endpoint where clients explicitly define the shape, depth, and fields of the data they need.

This flexibility shifts responsibility to documentation writers. Instead of cataloging dozens of static URL paths, documenting GraphQL requires articulating a strongly-typed Schema Definition Language (SDL), clarifying complex graph relationships, explaining execution boundaries such as query complexity and depth limits, and detailing schema federation across distributed subgraphs.

###CODEBLOCKPLACEHOLDER0###

1. Schema-Level Documentation via SDL Comments

In GraphQL, documentation is an integrated, first-class citizen embedded directly inside the schema definition. Schema descriptions placed above types, fields, inputs, and enums are automatically exposed through GraphQL introspection queries and displayed in developer tools such as Apollo Studio, GraphiQL, and GraphQL Voyager.

Notice the crucial syntax distinction:

• # Single-line comments: Treated as internal developer comments and ignored by the GraphQL introspection engine.


• """ Triple-quoted blocks """: Formal documentation descriptions parsed by introspection and rendered in all documentation tools. Markdown formatting (bold, links, code blocks) is fully supported inside triple-quoted strings.

###CODEBLOCKPLACEHOLDER1###

2. Documenting Mutations and Input Objects

Mutations cause persistent state mutations on the server and require careful documentation. When authoring documentation for mutations, technical writers must explicitly document:


1. Authorization Scopes: Which specific user roles or API token scopes are required (e.g., cluster:write).


2. Idempotency Guarantees: How client applications should use client-side tokens to prevent duplicate resource provisioning during network retries.


3. Field Validation Bounds: Minimum and maximum boundaries on numbers, string lengths, and regex formats.


4. Error Extensions: Custom GraphQL error codes returned in the extensions block when operations fail.

###CODEBLOCKPLACEHOLDER2###

3. Explaining GraphQL Error Handling Conventions

A frequent source of developer confusion is GraphQL's error handling model. Unlike REST, where HTTP status codes (404 Not Found, 401 Unauthorized) indicate failure, GraphQL requests typically return an HTTP 200 OK status with an errors array alongside partial data:

###CODEBLOCKPLACEHOLDER3###

Technical writers must maintain an explicit Error Extension Directory cataloging all domain codes:

Extension Code	HTTP Equivalent	Underlying Cause	Client Recovery Action
UNAUTHENTICATED	401	Missing or invalid Bearer JWT.	Renew token via authentication provider.
FORBIDDEN	403	Token lacks permissions for field.	Request elevated scope from workspace admin.
NOTFOUND	404	Targeted entity does not exist.	Check identifier spelling.
COMPLEXITYEXCEEDED	429	Query exceeds maximum depth limit.	Reduce nested field depth or paginate nodes.
RATE_LIMITED	429	Request frequency threshold reached.	Pause requests until specified cooldown timestamp.

4. Documenting Relay-Style Cursor Pagination

One of the most complex patterns for API consumers is cursor-based pagination. While offset-based pagination (offset=20&limit=10) suffers from data drift when items are inserted or deleted, Relay Cursor Connections provide stable pagination across dynamic lists.

When documenting cursor pagination, explain the relationship between Connections, Edges, and PageInfo:

###CODEBLOCKPLACEHOLDER4###

Accompanying Developer Query Example

Always provide developers with an exact query demonstrating how to request the next page using after:

###CODEBLOCKPLACEHOLDER5###

5. Documenting Apollo Federation 2 and Supergraph Architecture

In enterprise microservices, multiple independent teams author distinct subgraphs (e.g., Billing Subgraph, Inventory Subgraph, Identity Subgraph). Apollo Federation 2 composes these disparate schemas into a single unified Supergraph gateway.

When writing developer documentation for a federated graph, you must explain:


5. Federation Directives: Clarify how @key, @shareable, @inaccessible, and @override control field ownership across subgraphs.


6. Entity Resolvers: How the gateway joins entities across boundaries using reference resolvers (__resolveReference).


7. Gateway Composition Rules: How continuous deployment uses rover subgraph publish to validate that new subgraph commits do not break the supergraph composition contract.

###CODEBLOCKPLACEHOLDER6###

By documenting entity ownership boundaries, upstream engineers know which team owns each schema attribute, eliminating inter-team ambiguity.

6. Documenting GraphQL Subscriptions over WebSockets

Unlike queries and mutations which operate over HTTP POST, subscriptions maintain a persistent stateful connection over WebSockets (using graphql-ws). Documentation must outline:


8. Connection Lifecycle: The WebSocket subprotocol negotiation (graphql-transport-ws).


9. Connection Initialization Payload: How authentication tokens must be sent inside the connection_init message rather than standard HTTP headers.


10. Heartbeats & Ping/Pong: How clients maintain connection liveness during periods of inactivity.

###CODEBLOCKPLACEHOLDER7###

7. Documenting Query Complexity and Security Hardening

Because clients can craft deeply nested queries (e.g., user { friends { friends { friends } } }), GraphQL APIs enforce query complexity scoring and depth limits to protect server resources.

Your documentation should explain:


11. Maximum Query Depth: The maximum level of nested relationships permitted (e.g., 5 levels deep).


12. Complexity Points System: How individual fields incur score penalties (scalar fields cost 1 point, connection lists cost 10 points per 20 nodes).


13. Automatic Persisted Queries (APQ): How production clients pre-register query hashes with the gateway, preventing arbitrary complex query execution from malicious callers.


14. Cost Header Inspections: How clients can inspect returned HTTP response headers such as X-GraphQL-Cost to stay within limits.

8. Automated GraphQL Documentation Generators

Maintaining GraphQL documentation manually in static markdown quickly leads to drift as developers add schema fields. Use automated documentation generators that read the live schema introspection and compile static HTML guides:

By embedding rich SDL triple-quote descriptions, cataloging error extensions, documenting federation schemas, and explaining complexity limits, you give developers the exact guidance needed to build scalable GraphQL integrations.