GraphQL is a powerful tool for building queries to get your blog posts, products, and other data and content from third-party services and your own backend APIs.

You can access your data via GraphQL directly over HTTP, with no need for libraries or SDKs, making it popular for cross-platform applications.

In this article, we'll show you how to write an example GraphQL query and use it to get data via an HTTP request in cURL, Python, PHP, JavaScript, Ruby, Java, and Postman.

How to write GraphQL queries

GraphQL is used to query data stored in backend systems, allowing you to fetch and manipulate data through an HTTP API.

The examples in this tutorial use a simple GraphQL API that provides information from an employee database that contains a unique ID for each employee, their name, job title, the date they started working there, and optionally, their age. Below is the GraphQL schema that models this:

You can use this schema as a template for getting started and modify it to match your own data. If you want to try out any of the example code in these articles with the example employee schema, you can mock it by simulating a GraphQL API — a powerful tool for developers who want to start working on their frontend queries but are yet to build out their backend. 

If you're a Contentful user, it’s even easier to learn GraphQL — you can also start learning GraphQL right here in your browser (without having to mock servers or debug using cURL) using our GraphQL Playground and use GraphQL to query your blog posts, products, and any other content you create on the Contentful Composable Content Platform.

Once you have the schema of the data you want to query with GraphQL, you can write your query. The example query below searches the example schema above for employees with the job title "janitor":

Now, let's see it in action in a variety of popular programming languages and environments.

1. How to make a GraphQL query with cURL/bash

To start, let’s make a GraphQL request via cURL. cURL is run from the terminal, and is a good way to explore queries before implementing them in a specific programming language, allowing you to see what your response should look like before implementing and debugging it.

Note that in all of the code snippets on this page, we'll use example.com as the API endpoint, so you’ll need to replace that with your actual endpoint. All of the HTTP API requests on this page use the HTTP POST method, as they submit GraphQL query data to the backend. 

Below is a complete example of a cURL command that queries an HTTP GraphQL API from the command line:

In the above command, the -X option specifies the POST request method. The  -H option sets the Content-Type header (GraphQL APIs send their response in the JSON format) as well as the Authorization header (if your API requires an authorization token). The -d option sets the data that will be sent in the POST request — in this case our GraphQL janitor search query. 

The output from the above example cURL command looks like this:

The response includes any matching records from your API. If an error occurs, an error object will be returned instead, containing the details of the problem encountered.

2. How to send a GraphQL request using Python

There are few different ways to make an HTTP request in Python. I’m a fan of the requests library. It’s extremely simple to use — although, unlike urllib, you will have to install it.

Below is an example Python script that uses the requests library to make the GraphQL query via HTTP:

Once run, the JSON output of the query will be returned, just as it was with cURL.

3. Making GraphQL HTTP requests from a PHP client

There's no need to install any additional libraries to make GraphQL HTTP requests from PHP clients. You can use the built-in stream_context_create function to complete the request and then use the file_get_contents function to read the contents of the response.

If you wish to convert the JSON response string to a PHP object, you can parse it using the json_decode function:

4. GraphQL from JavaScript and Node.js

How you make GraphQL requests in JavaScript depends on whether you're running your code from a web browser or in a Node.js environment.

JavaScript (Browser)

JavaScript's Fetch API lets you make HTTP requests from JavaScript with a simplified syntax. The code below sends the example GraphQL query using fetch, and prints the response to the console after it is received:

JavaScript (Node.js)

Node.js doesn't have the Fetch API built in, but you can add an equivalent by installing the node-fetch package. While there are a few differences from using fetch in the browser, for most purposes it is the same:

Note that the above example script will need to be saved to a .mjs file (for example, run_query.mjs) as recent versions of node-fetch need to be imported as a JavaScript module.

5. Making GraphQL HTTP requests in Ruby

Making HTTP requests with Ruby can be done without installing libraries. The net/http, JSON, and URI modules used in the following example are already built into Ruby:

6. GraphQL requests in Java

Making HTTP requests in Java can be very verbose; in versions prior to Java 11, it required manually opening connections and reading and writing data. The OkHttp library makes writing HTTP requests in Java much simpler. 

The example GraphQL query below is made in Java using OkHttp:

7. Using Postman to test GraphQL requests

Postman, like cURL, is a tool for making HTTP requests, and is designed for testing APIs. Many developers prefer it as it lets them write HTTP requests including GraphQL queries, then test and debug them, all from a streamlined, user-friendly interface. 

Postman includes a specific GraphQL mode for making GraphQL requests via HTTP, allowing you to set HTTP headers, write your queries, and set variable values, and import GraphQL schemas. It even validates your GraphQL query syntax.

To access the GraphQL mode in Postman, go to File > New and select the GraphQL request type:

Then, enter the URL to your GraphQL endpoint and enter your GraphQL query into the Query box:

And that’s it! The results of your query will be shown in the Response body. Postman lets you test different APIs and applications in different tabs, each with their own headers and settings, and records the history of each request, making debugging your GraphQL queries much simpler.

Using GraphQL with Contentful

Once you've figured out how to make GraphQL queries via HTTP requests in your language of choice, you'll want to use your new skills to build something cool. That's where Contentful comes in! Using our Composable Content Platform, you can define content like blog posts, images, videos, and products, and then retrieve all of their data via our GraphQL content API.

By building on Contentful, you can publish your content to all of your apps and websites, and have all of them pull their content via GraphQL, whether you're using PHP, JavaScript, Java, Ruby, or any other programming language or platform. Our headless CMS lets you define your content and what it looks like, including the fields and attributes you need for your apps, and create, edit, and live preview your content exactly how it will look to your users.

If you want to see a full example of using GraphQL with Contentful, including using GraphQL variables in queries to give type safety in TypeScript, check this out. 

We also have a full GraphQL course available to make it as easy as possible for developers to hit the ground running with GraphQL. See how to get started with GraphQL, React, and Contentful, covering GraphQL tooling, fragments, directives, variables, and query complexity costs (and much more).

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.