What the GraphQL
So of course Facebook, being Facebook, decided that RESTFUL APIs weren’t good enough when transmitting data to our mobile devices. Our cellular data is precious for those who don’t enjoy the luxury that is unlimited data. They needed a way to only serve up what the client asks for, doing so would result in smaller, more precise network requests which would shorten load time. In 2015, Facebook publicly released GraphQL, an alternative to REST.
It turns this:
Into this:
GraphQL allows Back-End and Front-End engineers to really focus on their platform and determine how much of what data is going to be presented. Usually a GET request to some API, lets say GitHub for instance, requesting to see view data for a Repo, will return you and bunch of nonsense and un-useful URLs. GraphQL allows for schemas to define the Types of data you will be serving up (which works nice with React Component naming), and the Fields for those Types (Props).
Each of these Types will have a corresponding ES6 class with its methods representing the Fields. This structure makes unit testing a dream, as all that needs to be tested are the classes and their methods.
Once all the classes are created, in order to actually get data back to the client, they must specify what data they need with Queries. Queries get structured in the schema, and are what the client use to request data. These Queries are then created into resolver functions which are the bridge between the schema and the classes.
An overlooked benefit I see with GraphQL is the amount of endpoints. When working with GraphQL, clients make POST requests to a single endpoint, which respond with the queried data. Most RESTFUL APIs have at least 4 endpoints for each of their databases (4 X # of DB). Now we must take into consideration that though there is only one endpoint, the queries that are made to it can be very complex, but this is made simpler by using GraphiQL, a Web-interface that allows you to test queries to your GraphQL server, and can even pre-supply queries and fields.
So is it hard?
Not really.
At first it’s really confusing if you’re unfamiliar using a MVC file structure (focusing on the Model). But after getting the classes set up (the Models), the only thing that is really different is the schema. The most import thing you do when creating a GraphQL based API is get your schema down before writing any code. Really take your time at the beginning to think of all the edge cases and how all of your Types relate to one another. Maybe your Organizations Type has a repos Field which is just a list of repos, then that has to be considered in the schema by having that repos Field be equal to an array of Type Repo.
Here are some tips I’ve learned while using GraphQL that might help you out.
When a Field on a Type is just a collection of a Type, name the Field plural (ie: if Type === Repo { Field = repos}) and set it equal to an array of the Type (repos: [Repo])
Definitely use ES6 classes for modeling your Types
Each field should either return a String, Integer, Id, or another Type
Each Type should have some sort of input, and it helps if that input is some sort of object that resembles that class. Makes setting up Fields easier.
