This is the first in a series of blog posts where I’ll be covering three topics relating to GraphQL:
- What is GraphQL?
- Building a basic API with Rails
- Some best practices
Yes, GraphQL has been around for a while already. The reason why I decided to write this series is because Github recently released its GraphQL API alpha. Github has been at the forefront of API-driven development for some time now, and its RESTful API is an exemplary API design referenced by many developers. So it’s always pretty interesting to explore new Github releases.
Alright, let’s get started!
What is GraphQL?
First things first, the best way to learn GraphQL is by practising GraphQL. I highly encourage you to play around with some GraphQL tutorials — especially the ones at graphql.org, and Github GraphQL API. Both are very good resources to play around with and learn some stuff.
So, what’s GraphQL? The official definition is: a query language for your API.
Don’t look at me, it’s the definition from graphql.org :) So what does this mean? Let’s take a look at an example to get a better idea:
Yes, it really is as simple as that. You pass your GraphQL query as a parameter in your API request and then let the server figure out how to translate your query into a real SQL (or any other kind of QL that the server might be working with), execute it, and return the data you’ve requested.
Why was GraphQL born? What are the benefits of using GraphQL, instead of RESTful or RPC API?
There are two points of view on the benefits of GraphQL for developers.
The frontend developer’s view:
- I can get many resources in a single request; and
- I can customise the response to be what I want it to be.
As we see in the example, as a frontend developer you can get many resources with a single request — unlike RESTful API, where every endpoint is a resource, and to get multiple resources you have to send and process multiple requests. Also, you can even customise your response names, which makes your life easier when it comes to mapping them onto the models, etc.
The backend developer’s view:
- Versionless API;
- No API documentation; and
- Introspection system.
One of the best practices of the GraphQL API is that you don’t version your API. By defining your resource type, you don’t need to specify what your API response should look like — your frontend friends will specify it themselves by giving you the query they want. So it’s almost like you only need to define your model abstraction layer for the frontend, leaving everything else to them.
Moreover, you don’t need to write API documents anymore (thank god!), because by defining your resource (its type, or API model), you also provide the ability to introspect it (think swagger vs. JSON-schema). Your frontend friends can explore the types, and figure out what they need, and request the necessary data from you.
GraphQL vs. REST and RPC
Let’s take a look at the difference between GraphQL, REST and RPC to make things even clearer:
In REST, every endpoint is a resource. In RPC, it is a function. However, in GraphQL we feed the endpoint with sql-like commands passed via query parameter (of course, it’s not a “real” SQL).
And just before we jump into writing some code, let’s remember an important thing: the separation of concerns. Broadly speaking, this means that whatever API layer or implementation you choose to put on top of your code, it should not change or affect that actual business logic, but wrap it and let your external clients interact with it.
Quoting GraphQL’s “Thinking in Graphs” page:
Where should you define the actual business logic? Where should you perform validation and authorization checks? The answer: inside a dedicated business logic layer. Your business logic layer should act as the single source of truth for enforcing business domain rules.
Ok, enough theory, let’s write code! Read on here: Part 2: Building a GraphQL API in Rails — Part 2.
by Wayne Chu.