A Beginner’s Guide to GraphQL API Queries and Mutations

There’s more data out there than most apps can reasonably use. Billions of results for the most common Google searches. Millions of products for sale on Amazon. Hundreds of thousands of new social media posts every minute.

Even for something smaller like your company’s digital signage, you might have dozens of screens across each of your company’s locations, each with hundreds of slides, apps, integrations, and playlists filled with content.

Traditional APIs won’t cut it when you need to drill down through that much data.

Which is why the Facebook team built GraphQL.

If you’re Facebook, with a business built on user-generated content, you don’t want to send all of that data every time an app requests, say, someone’s profile info. It’d be much better to filter things down and send only the most important data. With GraphQL, you don’t just GET a user profile REST API request—you tell a GraphQL endpoint that you want that user’s name, username, and profile photo, and get back exactly that data, nothing else.

If you’re used to webhooks and REST APIs, you might find GraphQL a bit confusing at first. In this tutorial, we’re going to use digital signage platform ScreenCloud’s GraphQL API but with a little practice, you’ll be requesting and mutating data with the best of them.

GraphQL vs REST: How to Make API Requests

The quickest way to make an API request to fetch data from either a REST API or a GraphQL API is directly from Terminal on your computer.

Say you wanted to get data from one of the many public APIs that curate data. You could open Terminal, type curl --location 'URL' and get back the info you want. For example, you could enter the following command to send form-formatted text to search the Open Library for the book "The Information a History":

curl --location 'http://openlibrary.org/search.json?q=the%2Binformation%2Ba%2Bhistory'

Moments later, you’d get back a list of details about James Gleick’s book "The Information: A History, a Theory, a Flood," along with 18,450 lines of JSON text about that book and others with titles that include the same words—perfect to build a book search app, less helpful if you need info about a single book. Or, perhaps, you could have a more precise query that only returned that one specific book—but even still, OpenLibrary’s REST API would have returned 347 lines of info about "The Information" specifically.

A GraphQL API can be equally verbose—if you ask it to be. But since you have to tell a GraphQL API exactly what data you want, it’s a bit more difficult to write your first queries. But you’re also more likely to get precisely the data you want.

Say you wanted to get a list of every country in the world, with the open Countries GraphQL API. You could enter the following query in Terminal send GraphQL-formatted text (similar to JSON, without quotes and commas) to request the name and country code for every nation on earth:

curl -X POST
-H "Content-Type: application/json"
-d '{"query": "{ countries { code name } }"}'
https://countries.trevorblades.com/graphql

On a Windows PC in Command Prompt, you’d need to write the entire text in a single line and escape the double quotes with a backslash, like this:

curl -X POST -H "Content-Type: application/json" -d "{\"query\": \"{ countries { code name } }\"}" https://countries.trevorblades.com/graphql

Moments later, you’d get back a thousand lines of JSON text listing every country and its code.

Or, you could ask for something more precise. Now that you have each country’s code, you could get more details about a specific code like Canada with the following query (or, on a PC, remove the line breaks and add backslashes before the double quotes, as before):

curl -X POST \

    -H "Content-Type: application/json" \

    -d '{"query": "{ country(code: \"CA\") { name currency emoji continent { name } } }"}' \

    https://countries.trevorblades.com/graphql

Then you’ll get only the data you wanted, that Canada is located in North America, uses the Canadian dollar, a 🇨🇦 emoji.

That, in a brief nutshell, is how you’ll use GraphQL APIs. You might use a broader request to get a list of all data—say a list of every country’s name and code, just enough to find the country you want. Then you’ll make another request with that code to find the exact data you want—like a country’s emoji, or in Facebook’s example, the most recent photo you posted.

A Quick Guide to GraphQL Terms

With a REST API, you might use a POST request to send data to an API, a GET request to look up data from an API, and a PUT request to update data via an API call. Each API call would use a unique API Endpoint. For example, with Gmail’s REST API, you’d send a POST request to https://gmail.googleapis.com/gmail/v1/users/{userId}/drafts to create a draft email, but would send a GET request to https://gmail.googleapis.com/gmail/v1/users/{userId}/drafts to get a list of all draft emails in an account.

GraphQL changes things up. You have a single API endpoint to send and request data. For example, with ScreenCloud’s digital signage GraphQL API, every request you make is a POST request to https://graphql.us.screencloud.com/graphql.

You then have to request what you want. GraphQL APIs include:

• Queries to look up data
• Mutations to create and update or edit data
• Objects to list a set of fields about something, such as a screen` in ScreenCloud
• Fields to list individual details in an object, such as a screen’s `name` or `id` in ScreenCloud
• Arguments to pass data along with an object, such as including a screen’s ID number to request data about it including if it’s turned on or not, or the `code` in the country query above.

There are also a few common elements in GraphQL APIs that follow written English conventions. For example, there’s an `allScreens` query to find info about a specific screen in a ScreenCloud account, a `screens` query to get a list of every screen in a ScreenCloud account, and a `createScreen` mutation to add a new screen to your account. Non-plural queries get info about a single object, plural queries get info about every object of that type, and verbNoun (in camelCase) queries are mutations to do the verb to the noun object (say, to `create` a `screen`).

And you can do all of it together. Let’s build a few GraphQL requests to get the hang of it.

How to Build a GraphQL Request

The quickest way to start making GraphQL queries—if a bit geeky—is to use Terminal on a Mac or Linux computer, or Command Prompt on a Windows PC, as above.

To make a GraphQL request in Terminal, you’ll:

• Start with curl -X POST to use the curl app to POST data to a URL
• Add -H "Content-Type: application/json" to tell the server that you’re sending JSON-formatted data
• Add -H "Authorization: Bearer YOUR_TOKEN", replacing `YOUR_TOKEN` with an authorization or API key, if your GraphQL API requires authentication
• Add your query, such as -d '{"query": "{ object(argument: "text") { field field2 sub-object { sub-field } } }"}', replacing the object, argument, and field names
• Finish up with your URL, such as https://studio.us.screencloud.com/org/1/developer for the ScreenCloud GraphQL API

Say we want to find out if a specific screen is currently turned on, in ScreenCloud. To do that, we’d first need to find that screen’s ID number, and then would need to request details about that screen.

First, you’ll need an authorization token for ScreenCloud. Open your ScreenCloud account’s developer settings, create a new token, select to give it full access (or, pick the specific GraphQL objects to allow access to—your choice) and copy the key. Note the GraphQL Endpoint URL for your account as well.

Then, pull together your query. We’ll first want to request every screen so we can find our screen’s ID number. For that, we’ll run a `screens` query like below to request every screen’s ID and name:

allScreens {nodes { id name } } 

That’ll give you a list of every screen’s name and ID.

Once you find the ID of the screen you want, then you could request info if it’s running or not with this query, replacing ID_NUMBER with your screen’s ID:

screenById(id: "ID_NUMBER") { status }

And a moment later, you’ll get back a response of "status": "LIVE" if your screen’s running.

The Best Ways to Query GraphQL APIs

You’ve got CURL commands down in Terminal and Command Prompt—and they’re good enough to get started.

Want to do more with your GraphQL APIs? Download Postman. It’s a tool built specifically to work with APIs, and it has deep GraphQL support today. Once you add a GraphQL API, Postman will list every query, mutation, object, and field to help you build calls quickly. And it’s free for most use cases.

Once you’ve got Postman installed, open a new tab, select GraphQL, and enter your ScreenCloud GraphQL Endpoint in the address bar. Click the Authorization tab, choose Bearer Token, and paste in your API key.

Then open the Query tab, and you can either type in a query or mutation, or build one by searching through and selecting queries, objects, and fields from the center column. Once you’re done, click the blue Query button, and you’ll see your results at the bottom of the screen.

Or, you can automate your GraphQL work using a no-code builder tool like Zapier, where you could, say, automatically turn on a screen on a schedule or add new files to your signage from Google Drive or set up a new Screen Group and folders for media whenever you kick off a new event.

In Zapier, select the Code step, then write JavaScript code to query or mutate data with the GraphQL API—or use Zapier’s AI to help write the code. For example, the following code  could create a folder in ScreenCloud for you to start a project, if you add in your Space ID and token:

mutation {

        createFolder(input: {

                name: "ZapierTest", // Replace with your folder name

                spaceId: "SPACE_ID" // Replace with the actual SpaceID

            }

            ){

                folder {

                            name

                }

            }

    }

    `;

    const token = 'YOUR_TOKEN'; // Replace with your actual token

    output = { result: data };

Run that step, and Zapier will parse the JSON code and give you the folder name—or any other data you request—to use in the next steps in your automation. And you could tweak that code to run any GraphQL query or mutation—using the exact same text as you’d use in Postman or Terminal, as long as you leave the core JavaScript code the same.

Time to Explore Your GraphQL APIs

And with that, you’re ready to explore on your own. Jump into ScreenCloud’s GraphQL documentation to see what all you can do with its queries and mutations, and try it on your own. Request different fields and objects, and see what you get back. Play with it, and think about how you could automate your team’s signage. Or, if your team doesn’t have any ScreenCloud-powered digital signage yet, sign up for a free 14 day ScreenCloud trial—and start out with GraphQL-powered automations right from the start.

Then, for a bit more fun, jump into our ScreenCloud Webhooks tutorial to build an automatically-updating dashboard in your ScreenCloud signage ... one that you could now tie in with the GraphQL API to, say, make a meta dashboard that displays which of your company’s ScreenCloud signs are currently active. The sky’s the limit!