What I learned about GraphQL and Make

[alex.newpath]

What I learned about GraphQL and Make

If you haven’t learned about GraphQL or have struggled with trying to get your GraphQL server to send back data, fear not.

Learn GraphQL.

Learn how it works from graphql.org and try the Star Wars GraphQL API StarWars GraphQL API. You won’t be sorry. It’s incumbent that you understand what GraphQL is: it is a Query Langauge (QL) for a graph. Here’s a pictorial representation of the StarWars Graph

It is very different from REST because you mostly use POST to send data via JSON and there is only 1 endpoint to query data from the graph. (Mutations modify the data model and subscriptions get real time updates but I won’t cover that here).

GraphQL Docs/Explorer

Make sure you have access to the GraphQL Docs/Explorer for your API. Without that doing some experiments will be very hard and you won’t be able to model your queries the way you want them to.

The data is returned in the “shape” you want it

GraphQL returns your data in the “shape” you want it to - you can query multiple objects, set filters, page and create joined data between multiple objects with one call. Instead of calling multiple REST API calls, GraphQL usually can return all the data you need in the way you need it with just 1 call. This is primarily the reason why Facebook invented it in 2012. It’s been around since 2015 as an open source project so not many APIs use it but some definitely have adopted GraphQL as an alternative and some support GraphQL as the only API architecture.

Gotchas

The HTTP module is very persnickety when it comes to the JSON payload. GraphQL data has carriage returns sometimes in the Explorer but Make doesn’t always like that and returns invalid JSON error before it even attempts to run the payload. Eliminate carriage returns and make sure any double quotes (") are escaped with a \"

Here’s a short little video of what I learned.

Make - 2025-12-09_21-50-17

And here is the scenario that you can view and clone into your own Make account to experiment.

Once I get mutations working (creating & updating data in the model with GraphQL) I’ll update this post

[alex.newpath]

All right, I am back with more learnings about GraphQL. Once you get the hang of creating queries, you’re going to want to know how to make updates to the data. This is done with something called “mutations”. Simply put, mutations are functions that are part of your GraphQL API documentation that are predefined “calls” that can modify the data.

mutation UpsertExternalRegistration {

insert_external_registrations_one (    

object: { 
     custom_id: "WildApricot Registration Occurred",      
     email: "{{5.foundemail}}",
     event_id:{{5.`OA Event ID`}} },
     on_conflict: {    
           constraint: external_registrations_email_event_id_key,
           update_columns: [email, custom_id]  }
                                  ) 

{    custom_id    
     email    
     event_id }
}

Let’s walk through this call line by line.

First of all, you have

mutation UpsertExternalRegistration

This is simply a declaration that you will be calling a mutation that will modify data, and you’ve given your mutation a name which can be anything you want.

The next line is

insert_external_registrations_one (

This is an example mutation I am using that will update an object called external_registrations. The name of the function call is important and it comes directly from the documentation of all mutations.

This function expects some data to be provided

object: { 
     custom_id: "WildApricot Registration Occurred",      
     email: "{{5.foundemail}}",
     event_id:{{5.`OA Event ID`}} },

Specifically, custom_id, email, and event_id are fields in the external_registrations object that will be inserted since this mutation will first try to insert a record using event_id and email, since that is the compound primary key of the external_registrations object.

The on_conflict clause will be used to update the record (i.e., upsert) if the insert is unsuccessful due to a primary key violation — a record already exists with these values.

   on_conflict: {    
           constraint: external_registrations_email_event_id_key,
           update_columns: [email, custom_id]  }

Here it will use the constraint that is predefined in the GraphQL documentation, which is email and event_id. If I am attempting to insert an existing row in external_registrations that already has this pair of data, then instead update the existing data with the values from email and custom_id that I have passed in above.

The final snippet is simply the resulting data I wish to be passed back from the HTTP module on a successful upsert. You can put whatever attributes are available from the external_registrations objects.

{    custom_id    
     email    
     event_id }
}

An IMPORTANT note: The GraphQL API I was dealing with requires body content to be on one line. Carriage returns in the body will terminate the body and cause an error to be sent back. Very frustrating — I need to unwrap the call to ensure there are no carriage returns. Unfortunately, since my app (Oxford Abstracts) did not have a ready-made app in Make, the HTTP modules I used were very finicky. Here’s a snapshot:

The documentation on your GraphQL API will have a set of mutations that are available, much like any REST API. You will have the ability to make changes, but you need to understand which mutation you’d like to use, and that will require you to read the docs on the mutation. It’s not as easy as just finding an endpoint that uses POST/DELETE/PATCH as method because all GraphQL queries use POST, including ones that have a mutation call.