What The Heck Is GraphQL

Definition

GraphQL in itself is a specification describing a new way an app or web frontend asks for data from the server. This specification is built into libraries we end up implementing on our server-side as well as the client-side of our apps. Meaning if you are building a web app that has no APIs this might not interest you.

How is this different from the way we write APIs at the moment?

If you have ever written or used an API before its most likely a REST API, RPC or some other variant. For the most part, these options expose a host of functionalities like data fetching or manipulation.

As a person using these APIs, you frequently ask the questions what endpoint do I call or ping to do X, Y, Z and sometimes in what order.

As the creator of these endpoints, you also find yourself asking the question what query do I need to write to perform X, Y, Z when an endpoint is called.

With GraphQL the Creator outsources the what query to write part directly to the consumer of the API, imagine if you had the ability to write SQL queries directly on the frontend!. Of cause doing that is dangerous but that's where GraphQL steps in to allow this in a safe way.

What benefit does this present?

For one aside configuring what resource/data the frontend has access to(authorization and authentication), there is no need for the server-side to create individual endpoints to dish out data to the client app/frontend. Another important benefit is that the client is able to request the data in their preferred structure, cherry-picking what they need and leaving out what they don’t need now for later. The client is literally in the driver's seat. With this, the client does not need to wait on the server-side developer to create endpoints to provide access to a data set.

Also, one other key thing is being able to craft complex queries, It's not called GraphQL for anything, You have the ability to ask for a big nest of related data, this saves you the hustle of multiple queries just to populate a screen. For example, you are able to pull a product together with its categories, orders and respective reviews all at once for one screen (App view) and omit one or more when you don’t need them for another screen(App view)

GraphQL terminologies?

Query: Remember when I mentioned GraphQL was similar to say writing a SQL statement but this time on the frontend? Well, you do actually write a query which is sent over to the server to run. This is how the client asks for data, by defining exactly how it wants it to the server. And since querying is a functionality of data persistence it is called operation type.

Schema Definition Language: A schema like its general meaning is a definition of your data structure, it defines relationships, fields, directives, validation rules, etc that apply to a particular data resource. Basically, this is where what is available to the client-side is defined and structured.

Fields: Again a word that is not too far from its well-known meaning. Fields are used within the schema to define properties that are available within data objects.

Types: The value of every field must have a type, this helps inform what data type to return when data is queried and what value type to expect during mutation. There a couple of types that are available from scalar types like strings, DateTime to Object types and Enums

Directives: Up until now all we have really defined is a data dump, but most apps are never complete without some way to query data how we want it ie: capitalize some titles, truncate long descriptions, hide some fields depending on who is asking for the data, or define some rules during insertion, this is what directives are for, to give directions, you get it :) In the example above its basically saying the User has many posts.

Mutation: Mutation is essentially how you add, update or delete data resources, resources with an S, meaning you can update multiple resources in one request, These will be run one after the other but you on the client will be sending this in one query. By the way, mutation is also an operation type just like Query.

What now?

There are other aspects like variable passing, arguments that we will not touch, you are better of finding out when and if you finally make the decision to use GraphQL.

Should I use it?

If you are heavily invested in building SPAs and or mobile. Using GraphQL will save you time writing a lot of APIs to expose functionalities to your frontend.

Most people are not yet invested so might be problematic if you are offering a public API , although powerful, somethings are very simple when done over REST or RPC.

How do I get started?

One of the best ways to get started with GraphQL is to find out how to implement it in your language or framework of choice and pick the option with the best documentation and tutorials available. You will find an official list of implementation for various languages here https://graphql.org/code/ [↗]

Conclusion

REST has its perfect use case, for example, a low learning curve which is useful when it comes to offering your endpoint to third party consumers, ultimately it's good to know GraphQL as one of the ways to dish out data to the client-side, its all about trade-offs, just know when to trade one for the other. Heck, you can have more than one way of dishing out data in a single project.

Here is another article you might like 😊 What the heck is Heatos?