This is a series blog post cover above three topics of GraphQL:
- About GraphQL
- Building a basic API with Rails
- Some best practices
GraphQL has been around for a while already, and it is not a new thing. The reason I decided to investigate it is because Github have recently released their GraphQL API alpha. Github has been on a forefront of API-driven development for quite some time now, and their RESTful API is an exemplary API design used as a reference by many developers - so it's pretty interesting to see what's new they have released.
This post is based on my talk at RoRoSyd Meetup - and if you'd like to know more, you can check my slides and an example repo.
Alright, let's get started!
First of all, the best way to learn GraphQL is to learn by doing, so I highly encourage you to play around with some GraphQL tutorials - especially the one at graphql.org, and also you can play with Github GraphQL API. Both are very good resources to play around and learn some stuff.
So, what's GraphQL?
The official definition is it's a query language for your API. Don't look at me, it's the definition from graphql.org :) So what does it mean? Let's take a look at an example to get a better idea about it:
It really is as simple as that - you pass your GraphQL query as a parameter in your API request, and 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 have 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 what GraphQL gives a developer.
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 it onto the models etc.
Backend developer's view:
- Versionless API
- No API documentation
- 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, and left 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.
Let's take a look at the difference between GraphQL, REST and RPC to make things more clearer:
## REST
GET https://myblog.com/articles
GET https://myblog.com/articles/1
POST https://myblog.com/articles?title=hello
## RPC
GET https://myblog.com/getAllArticles
GET https://myblog.com/getArticle?id=1
POST https://myblog.com/createArticle?title=hello
## GraphQL
GET https://myblog.com/graphql?query=graphql_query_here
POST https://myblog.com/graphql?query=graphql_query_hereIn 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 about an important thing that is a separation of concerns. In broader sense here, it means that whatever API layer or implementation you 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! See Building a GraphQL API in Rails - Part 2