This is a series blog post cover above three topics of GraphQL:
- About GraphQL
- Building a basic API with Rails
- Some best practices
GraphQL is not a new thing, it already exist for a while, the reason I decide to investigate it is because Github released their GraphQL API alpha currently. We know Github has been a very good company for a long time, their RESTful API also becomes some kind of standard for developers, so it's pretty interesting to see what’s new they've been released.
This topic is based on my Meetup talk, to know more you can check my slide and example repo.
Alright, Let's get started!
First of all, the best way to learn GraphQL is learning from doing, so I highly encourage you to play around with some GraphQL tutorial especially graphql.org, and also you can play with Github GraphQL API, they are very good resources to play around and learn some shit.
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 for a example and then you'll know:
Simple as that, you pass your GraphQL query as parameter in you API request, and let server handle how to translate your query to real SQL and execute it then return the value you want.
Why GraphQL born? What’s the benefit to use GraphQL but not using RESTful or RPC API? There are two points of view what GraphQL gave me.
As frontend developer’s view:
- I can get many resources in a single request
- Customise response to what I want
As we see in the example, as a frontend developer you can get many resources in a single request (not like RESTful API every endpoint is a resource, to get multiple resources you have to send multiple requests), also you can customise your response name which make your life easier to defend your model.
As 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 versioning your API, by defining your resource’s type, you don’t need to specify what your API response should looks like (your frontend friends will figure it out by passing query they want), so it’s like you only need to define your model abstraction layer to frontend and left everything else to them. Moreover, you don’t need to write API document anymore (thanks god!) because by defining your recourse (type, or say API model), you also provide the ability for self-introspections (like swagger v.s. JSON-schema), your frontend friends can explore the Types and figure it out what query they can use and are going to send to 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, we take every endpoint as a resource, in RPC we take it as a function. However in GraphQL, we take it like a sql command passed by query parameter (of course it’s not a “real” SQL).
Before we start writing code, take a look of how do we think in GraphQL, I’ll quote the point here and leave it to you to go deeper with this:
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 theoretically shit, let’s write code! See Building a GraphQL API in Rails - Part 2
Is it OK for you if we translate the gists part1 to part3 into Japanese and publish on our tech blog https://techracho.bpsinc.jp/ ?
We make sure to indicate the link to original and author name etc.
Best regards ,