What is a GraphQL request and how does it work?

GraphQL is a simple but powerful concept for API design: a single endpoint receives every GraphQL request and handles it by returning only the data the client asked for.

Like most API designs, GraphQL requests work over HTTP and can be tested using all the usual API tools. Though tools like Postman are popular for testing APIs in general, many GraphQL APIs offer in-browser explorers which make it easier to learn and experiment with queries. These explorers also come with a built-in documentation browser for the APIs schema.

While general-purpose API libraries (such as fetch, axios, or requests) can handle GraphQL requests, many developers prefer dedicated libraries, such as graphql-request for Node.js, which provide a number of helper methods for working with GraphQL.

Whichever library you end up using, understanding how GraphQL requests work is essential for writing efficient queries and getting the most out of any GraphQL API.

What is a GraphQL request?

If you’ve used APIs for some time, but GraphQL is new to you, you’re probably familiar with RESTful APIs. For example:

GET /posts/123

This is where the URL and the HTTP method define the resource you wish to access and the action to perform upon it. Any data to be processed will be sent in the body of the request.

Like RESTful requests, GraphQL requests are performed over HTTP and usually send and receive JSON data. Every URL is the same for a GraphQL API, and they primarily support the POST method. It’s the message body that specifies the action to be performed and the data to be processed. But more than that, it also specifies the data to be returned. An equivalent request to the above RESTful call would be:

The action to be performed is named in the message body by a GraphQL operation keyword. The three GraphQL operations are query (for reading data), mutation (for creating, updating or deleting data) and the less commonly used subscription (for real-time streaming).

To make use of GraphQL requests, it’s important to understand the schema behind the specific GraphQL API you're interacting with. This is because every request’s message body must have a structure that matches the data model it operates against. To retrieve data, you’ll need to provide a query that mirrors the schema being queried.

GraphQL requests make your life easier by allowing variables and fragments. Variables are placeholders that you define separately from the query to pass values at runtime that keep your queries clean and reusable. Fragments are reusable pieces of a query that let you define common field selections once and include them by name wherever needed, reducing duplication and improving maintainability and performance.

Finally, auth is handled much like any other HTTP request; for example, by authenticating against a dedicated endpoint, then passing the auth token in the HTTP request header:

Authorization: Bearer <AUTH_TOKEN>

If you’re making the request using a GraphQL client (for example, the graphql-request library or Apollo), the client will handle the headers for you. Otherwise, you’ll need to set the Content-Type and Accept headers:

How to use a GraphQL API

To use a GraphQL API, you send your GraphQL request to a single endpoint, adding your query to the request body. A common tool for doing this is Postman, but many GraphQL APIs have their own built-in tools (usually based on GraphiQL) that allow you to craft and test queries interactively. Once you've moved beyond the testing phase, you'll want to call the API directly in your code using a library or SDK.

To demonstrate, let’s look at a real-world example using Contentful's GraphQL API. Contentful is a content platform for managing and delivering structured content to websites and apps. A common use case is hosting blog posts.

The importance of understanding a GraphQL schema

Without knowing how to inspect the data model, it’s impossible to build a working GraphQL request — whether you're writing a query to read data or a mutation to modify it.

Unlike some APIs, GraphQL APIs will complain if you don't exactly match the structure of the request to the schema. For example, here’s an error generated when you request a field that doesn't exist in the schema for the blogPost type.

Most GraphQL APIs provide a built-in interactive schema explorer, like Contentful’s GraphQL explorer above, but if not, you can find out an API's exact schema with an introspection query. You can send this GraphQL introspection query to any GraphQL API and it’ll return the full schema, giving you all the information you need about its content model.

This GraphQL introspection query will return a large amount of information about every field and type in the schema. Running this query in Contentful's GraphQL explorer does this, but you can search for a particular field or type you're interested in.

You can then query more information about a specific field or type that you found in the scheme introspection query. For example, this query retrieves more information about the BlogPost type in Contentful's GraphQL API.

Sending a GraphQL request using Postman

Let's look at how you could use Postman to query for a list of blog posts in Contentful. The message body would look much like this, though this is a very simple example:

The code above is slightly prettified — please note that when actually sending this request, you’ll need to properly format the JSON without the new lines. Postman will warn you of this, as will the server.

Sending a GraphQL request using GraphiQL

As with many GraphQL APIs, Contentful also provides a GraphiQL-based interactive GraphQL explorer. As this was built specifically for GraphQL requests, the JSON you input into it can consist of just the GraphQL query; that means it doesn't need the surrounding JSON that Postman does:

Once you click the pink play button to execute your GraphQL request, your result will be shown on the right. If you've added some blog posts to your Contentful space, they’ll be returned in the result. 

On the left is the documentation explorer, which lets you navigate around the definition of the data model, viewing the data types and operations available on them. This is a great way to learn about the schema and understand how requests can be constructed. Clicking on items in the query will bring up a tooltip with a link to the relevant part of the schema explorer.

Sending a GraphQL request using the graphql-request library

Much like the explorer above, using a GraphQL library allows you to send only the query itself (without the extra JSON wrapper). GraphQL libraries also make it easy to automate queries programmatically in your code. 

For example, here's how you could send the same query using the Node.js graphql-request library:

How do GraphQL requests work?

GraphQL post request message bodies contain some important elements. Take a look at this slightly more complex example and we’ll see the variables it defines:

First, you have the operation type, which in this case is query. This informs the server that this is a request to fetch data, not an update or delete request. If it were, the keyword to use would be mutation. 

Next, there’s the operation name GetBlogPosts, followed by parentheses to pass in variables. If you don't need any variables, you can choose to skip the operation type, operation name, and parentheses entirely. 

Inside the operation, you need to name the field you want to operate on — in this case, blogPostCollection, which is a field consisting of a collection of blog posts. It would also be possible to query the field blogPost, but that’d only return a single blog post. So it's a common pattern in GraphQL APIs to define collections and use these to query lists of items. This is why blogPostCollection contains the items field.

Fields can take variables, and in this case, blogPostCollection takes two: $skip and $limit, which are used for pagination, seen here:

In this case, the query will return the second page of 10 items by telling the server to skip the first 10 results and return the second 10 results.

So far we have covered non-leaf fields such as blogPostCollection, blogPost, and items, which return either a single object or a list of objects; but deeper within a GraphQL query are the leaf fields, such as title, which return scalar values like strings or numbers. These leaf fields specify the exact structure of the data to be returned in the response.

Performance and scalability

Just as GraphQL APIs are built for performance, your requests should be too. The best way to do this is to understand what data you’re expecting from the API and use only those types in the request. If you need a single blog post, don’t request the full list. Similarly, if you only need the title and publication date, don’t request every field in the type.

You should avoid nesting queries excessively, because deeply nested structures can increase response times and strain server resources. While GraphQL does allow you to request related data in a single query, it’s important to fetch only the nested fields you really need. To keep responses fast and manageable, consider breaking complex queries into smaller ones if they retrieve excessive or rarely used data.

You should also consider using a GraphQL client with built-in caching features, such as graphql-request, Apollo, Relay and urql. These clients all have caching functions that populate responses before requests have fully returned. Your client application can even proactively populate the cache and manage it directly when necessary.

Caching, of course, helps in reducing repeated requests. You can help the client recognize when elements don’t need to be sent to the server by structuring your queries properly. Do this by requesting only the specific fields needed for the UI, avoiding over fetching, and reusing fragments to keep the query concise and efficient.

Putting GraphQL requests into practice

GraphQL requests give you a precise level of control over the data you fetch, as you decide the exact shape of data your application requires. Now that you understand how they work and how to query the structure of any GraphQL schema, you can build apps more quickly and with better performance.

Tools like Postman, GraphiQL, and especially GraphQL client libraries like graphql-request or Apollo, can make integrating GraphQL data into your applications even easier.

Contentful's content platform provides a flexible GraphQL API supported by powerful data modeling tools, including a visual GraphQL explorer that makes it easy to understand your data model’s schema. The API allows you to query the exact content you need — without needing to build a custom back end.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.