How do I GraphQL?
Top 3 things to know coming from REST
GraphQL’s query language is very easy to understand. For most people, it clicks immediately and doesn’t require much explanation. Thanks to GraphQL’s type system and tools like GraphiQL — a query builder/editor for GraphQL — learning GraphQL isn’t hard at all, and its advantages over traditional RESTful APIs become obvious quite quickly.
Given GraphQL’s clear advantages, almost every developer I’ve talked to is eager to try it out. Here are the questions they ask:
Question 1: Is GraphQL easy to secure?
Question 2: Is it easy to build a GraphQL server?
Question 3: Can I use GraphQL with <Angular/React/Ember/Redux>?
The good news is: these questions are easy to answer with GraphQL!
1. Is GraphQL easy to secure?
When most people hear GraphQL they hear “query language”, and think of a query language like SQL, but for graphs. To be honest, I thought the same thing when I heard it the first time! But GraphQL is an application query language. What’s an application query language, you ask? Think of it as a structured way of making REST calls: these queries are specific to your application, not to the database that holds your data.
In an application query language, you ask for things like “Person in age group teens” and not “SELECT * FROM people WHERE age > 12 AND age < 20”. The former is how clients ask for data from the server, and the latter is how the server might fetch that data — and clients don’t need to know about that. All the client needs to know is that the application has an age group called teens.
So instead of exposing all the capabilities of your various backends and databases, GraphQL exposes only those that your application needs, and it controls that access tightly. In fact, I’d say that GraphQL servers are easier to secure than traditional RESTful APIs, because the schema makes it very easy to reason about what parameters clients can send in requests, how the request is fulfilled, and what data will be returned.
2. Is it easy to build a GraphQL server?
GraphQL servers are really easy to build. Unfortunately, because GraphQL is catching on so quickly, the documentation available about how to build GraphQL servers isn’t as extensive as it could be. Also, the few tutorials that exist — my own included — don’t do a good enough job of explaining how to think about building a GraphQL server when coming from a REST background.
GraphQL servers are actually very easy to build, especially compared to a traditional RESTful API. All you need to do is define a schema — essentially a directory of the data types in your application — and resolve functions that tell the server where and how to fetch the data for each data type.
To put things in RESTful terms, which you may be more familiar with:
The schema is just like writing a Swagger documentation for your API, except that in GraphQL the schema is always enforced. The schema also completely removes the need for you to specify a router and parse url patterns. Having a strictly enforced schema ensures that documentation is always complete and up to date.
The resolve functions are similar to the code you would write inside your REST endpoints, except that each of them has a clear responsibility for fetching items of just one type. I have yet to see a REST API where code is organized as neatly as it is in GraphQL.
Because GraphQL gives you a logical structure in which to fit your code, I found that building GraphQL servers is much faster and easier than building a REST API.
3. Can I use GraphQL with <Angular/React/Ember/Redux>?
For a while, Relay was the only open-source GraphQL client available, but that isn’t true now.
Now, Relay is just one of many GraphQL clients, and you don’t have to use it to try GraphQL. There are other clients available, such as Apollo Client or Lokka. You could even use GraphQL without any client and send raw strings to the server, like you do for REST!
Relay is the JavaScript client for GraphQL that Facebook uses. It’s an impressive piece of software that adds many things on top of GraphQL, such as query merging, pagination and deferred queries. Relay is pretty tightly integrated with React and doesn’t support other view layers — at least not at the moment. It solves many difficult problems, which makes it quite complex: Relay can have a pretty steep learning curve.
While Relay is without a doubt the best GraphQL client at Facebook’s level of complexity, many developers we’ve talked to wish there was something simpler they could use. Others have apps in Angular or Ember, or they want Redux to manage all of their app state. In many of these cases, Relay is not the ideal choice.
So what alternatives are there?
If you’re looking for a client that does caching and integrates well with your view layer and state management, Apollo Client is probably your best choice: It’s easy to use and well-documented. It has integrations for React, Redux and Angular 2, and other integrations — for example React Native — are actively being worked on.
If you’re looking for a simple tool that just helps you send GraphQL queries and responses, take a look at Lokka. It clocks in at barely over 100 lines of code, which shows how simple a GraphQL client can be.
Conclusion
If you were curious about GraphQL before, but didn’t know everything you needed to know to try it out, I hope this post fixed that. If there are other questions that are keeping you from trying it out, let me know in the comments!
If this post got you interested in building a GraphQL server, you might find my GraphQL server tutorial useful, which also has a screencast that you can follow along.
