Why URL-Based Query Syntax Matters
GraphQL's query language allows clients to request exactly the data they need, but these queries are typically sent as POST requests with JSON bodies. However, there are compelling use cases for URL-based GraphQL queries: sharing links to specific data views, enabling browser bookmarking of query results, supporting GET requests for caching purposes, and integrating with systems that prefer URL-based APIs.
The GraphQL specification recommends supporting GET requests for query operations, with the query string provided in the query parameter of the URL. This capability opens up GraphQL to a wider range of use cases while maintaining the language's core benefits. Our web development services include API design and implementation to help you build robust, accessible endpoints.
https://api.example.com/graphql?query={user(id:"123"){name email}}
// URL-encoded version
https://api.example.com/graphql?query={user(id:%22123%22){name%20email}}Designing a URL-Friendly Query Syntax
The challenge lies in translating GraphQL's rich, multi-line query language into a format that fits comfortably within URL constraints while remaining readable and writable. Several approaches have emerged in the industry, each balancing readability, brevity, and URL safety differently.
Direct GraphQL String Encoding
The most straightforward approach involves URL-encoding the full GraphQL query string and passing it as the query parameter. This method preserves the exact GraphQL syntax and requires minimal transformation. While simple, this approach can result in long URLs and may hit browser or server URL length limits for complex queries.
Compact Query Syntax
A more sophisticated approach designs a compact query syntax that reduces character count while maintaining readability:
# Compact syntax example
u(id:123){n,e} # user(id: "123") { name, email }
This approach requires client and server to agree on the compact format, but can significantly reduce URL length for common queries.
Key considerations for integrating URL-based GraphQL queries with HTTP
GET Request Support
GraphQL servers should support GET requests for query operations, with the query provided in the URL query string parameter.
Variable Handling
Query variables can be sent as a JSON-encoded string in an additional 'variables' URL parameter.
Operation Selection
For queries with multiple named operations, use the 'operationName' parameter to specify which to execute.
Content-Type Headers
Clients should indicate preferred response formats using the Accept header, typically including application/graphql-response+json.
Naming Conventions for Consistency
Consistent naming across your GraphQL API becomes especially important when exposing operations via URLs, as poorly named queries can lead to confusion and errors.
Type Names
Use PascalCase for type names, which clearly distinguishes types from fields in URLs and query strings:
User, Product, OrderItem, PaymentMethod
Field and Argument Names
Use camelCase for field and argument names, following JavaScript conventions:
firstName, createdAt, orderBy, filterBy
Enum Values
Use UPPER_SNAKE_CASE for enum values to distinguish them from other identifiers:
ACTIVE, PENDING_APPROVAL, ORDER_SHIPPED
Following consistent naming conventions is essential for maintainable API design and helps teams work more efficiently across large codebases.
| Character | URL-Encoded | Description |
|---|---|---|
| Space | %20 | Represents whitespace in queries |
| { | %7B | Opening curly brace |
| } | %7D | Closing curly brace |
| " | %22 | Double quote for string values |
| & | %26 | Parameter separator |
| , | %2C | Field/list separator |
Encoding and Escaping Considerations
URL-based queries must properly handle special characters to ensure URLs remain valid and correctly interpreted.
URL Encoding Requirements
GraphQL queries often contain characters that have special meaning in URLs or can break URL parsing: curly braces, quotes, commas, and spaces. All query parameters must be properly URL-encoded to prevent parsing errors and ensure reliable transmission.
Unicode and Special Characters
For queries containing non-ASCII characters or special symbols, ensure your encoding handles Unicode correctly. GraphQL strings may contain escaped Unicode characters that need proper URL encoding to maintain their intended values through the request lifecycle.
Query Variable Encoding
When passing variables through URL parameters, encode the entire JSON object string. This includes escaping quotes, brackets, and other JSON-special characters within the variable values. Proper encoding is critical for API security and preventing injection vulnerabilities.
https://api.example.com/graphql?
query=query%20GetUser($id%3AID!)%7Buser(id%3A$id)%7Bname%20email%20posts(limit%3A5)%7Bid%20title%7D%7D%7D&
variables=%7B%22id%22%3A%22123%22%7D&
operationName=GetUser
// Decoded for readability:
// query = query GetUser($id: ID!) { user(id: $id) { name email posts(limit: 5) { id title } } }
// variables = { "id": "123" }
// operationName = GetUser