GraphQL Benefits in a REST API, But How?

GraphQL is an open sourced API specification from Facebook that is touted as the next evolution from RESTful APIs.  The primary benefits at a high level is a reduction in how many times an endpoint (or multiple endpoints) are called to get only the information that is requested.  In doing so, solves the problem of over and under fetching in the JSON payload.  Hold the pickles, thank you.

The primary driver of this specification was to better navigate dodgy network speeds for mobile applications.  GraphQL APIs allows you to only fetch the information you need, thereby preserving bandwidth that might otherwise be taken by larger payloads.  At almost 621MB in size with both the Facebook and Facebook Messenger apps, there is already a strong pull on the user’s device (Aug. 2017 iOS).

GraphQL is a query language (hence the QL) built on a schema to only query specific points in the data structure, compared to the entire JSON payload of a REST API call.  This can be very beneficial in use cases noted above like mobile where only certain parts of the application’s UI need to be updated to increase overall speed.  GraphQL is often used alongside with React & Redux on the front end to serve up specific new components when needed.  

Let’s take a look at the difference in the calls:

Image credit: howtographql.com.

Making this request is a query, similar to a GET call.  Modifying the data as part of the Create, Retrieve, Update  and Delete pattern (CRUD) is called a mutation.  All of your queries and mutations are set within your GraphQL schema for the API.  When looking to build out your own schema here is a great cheat sheet for the schema language and its types.

Another key benefit is the ability to combine what would be separate POST & GET calls into one, because of the deep nesting built into a schema.  For example, you are able to create a new user and assign an id attribute to that user, as a piece of that new user’s data.  Then receive the updated unique id from the server for that user in the response payload.  All of that is completed in one request-response round trip.   Beam me up Scotty!

Image credit: howtographql.com.

But what about incoming events...like from the internet?

Enter subscriptions.  Subscriptions keep a direct line to the API so when events occur they are streamed to the client.  Subscriptions are however very new and were just recently merged in March as a part of the overall GraphQL specification.  We will likely see subscriptions emerge as changes to current webhooks so they act closer to streams.

This is glorious! Throw out the REST APIs! Viva la GraphQL! (“Graph, Graph, Graph” echoing chants in the background)

What does this mean for Cloud Elements and our 100% RESTful API Platform?  Well the short answer is we kind of already solve this problem, using the REST you already know.  Let me explain.

The vast majority of large scale APIs are RESTful, serving up structured JSON payloads.  This creates an enormous amount of consistency in both what the provider can test for in sending and what the client expects to receive.  But even with this consistency, not every API is built the same, in fact far from it.  Some support webhooks, but a majority are still using polling.  Even then, 15% of all public APIs are still SOAP, the API structure that REST was supposed to kill off.  

Each cloud application (or Element) in our catalog is structured with our own query language (CEQL).   This allows us to make a normalized one-to-many API call across different Elements (our Hubs) and combine the payloads.  For example, the GET: /hubs/crm/contacts call will return the same contact structure across Salesforce, Sugar, ZOHO and Microsoft Dynamics (p.s. Microsoft Dynamics is actually a SOAP SDK...oh dear).

Great, but that doesn’t explain how you solve the over-under fetching?

The magic comes with our Transformations, the ability to map the data fields in each of the Elements to a customized data structure.  Now imagine you only want to GET a unique contact’s email, phone number and zip code from ZOHO and POST it to HubSpot? Our transformations pull the full JSON payload, strips everything but the requested data and only transmits the needed fields into the Element you want.

Finally, GraphQL itself is only a specification, similar to the Open API Initiative specification.  In order to actually build and implement your new GraphQL based API there are vendors like graph.cool alongside a whole community of plugins, servers, and even a CMS.  

There is a strong shift in adopting GraphQL by digital content providers like Twitter, Pinterest, and even the Financial Times.  Therefore we will continue to support the API community as the progression towards newer specifications becomes more mature.  Regardless of the endpoint, we will power your integration strategy, sign up for a developer account to play with your own transformations.