So What is GraphQL anyway?
An alternative for REST and so much more.
What is GraphQL you may be wondering. A specification. An alternative to REST. A query language. A runtime for fulfilling API calls. All of these are true but none of them alone convey what GraphQL is. Let’s go through each of these and explain what they are.
A specification:
There is no specific software that you must purchase or run to use GraphQL. All that is provided is a rest of rules for how to make operations work. Similar to http or REST, there are just rules of how to communicate but the exact how is up to the software community. Here are the specifications if you want to read them yourself: https://facebook.github.io/graphql/
As you might have guessed from the link above, Facebook originally created the specification. The problem Facebook was trying to solve was making data retrieval and management more efficient for it’s Android and iPhone apps that were relying on slower & data limited wireless networks and mobile devices not continuously connected to power. We will get more into how that is done in later sections. Facebook open sourced GraphQL in 2015.
An alternative to REST:
REST has been the de facto standard for API architecture for 20 years. It is defined by it’s GET, PUT, POST, DELETE operations. The biggest problem with traditional REST APIs is scope. A client is likely to need multiple APIs to complete many data requests or have the API overfill your request. For example, take the case of trying to create a web page of actors and information about their films. You very well would need to call at least 2 different APIs, one for the actor bio information and other for information about the films. If all of this data is sent in one API call there will probably be overkill on many get requests that receive more information that they actually need. This causes extra load on the server which has to gather and send the data, network, and leaving the client device to have to sift through the data to find the bits they need.
What GraphQL does differently is to allow the end point to select what exact information it needs. The information can come from multiple internal end points and even include data from external endpoints. The data is also formatted exactly how it is requested to make the load on the front end easier. That leads us to…
Query language:
The part that your end users will see is your endpoint. And that involves getting or changing data. Just like REST, GraphQL can handle all of these.
The most common activity is query which is synonymous with Get in REST. Below is sample of what a query might look like for a simple article feed of one article.
To change data (POST, PUT, DELETE) you use mutations. Below is a sample POST mutation to create a record.
Other GraphQL Functions:
Authentication — User authentication including sign-up and sign-in can be done natively. This can then be used in verifying the user to do tasks with that database such as mutations or subscriptions.
Subscriptions — Allow a client to ‘subscribe’ to a defined feed so that new/updated items will be pushed to them automatically. Can be used for updating data creation, updating, or deletion. Can have multi-tiered subscriptions such an article with an upvote, the user who wrote the article, and the upvoter.
Filter — Allows the ability to set a parameter to that will search the specified fields, such as URL and the item description, only for the word. This, again, allows for a narrower more specific set of data to be provided to the client.
Sorting — Allows results to returned in an order specified such as alphabetical by author name or publish date.
Pagination — Returns the specific number of items per page. Allows the user to receive smaller chunks of data and to see more items in an organized way. Users can go forward or backwards through the pages by making extra calls. Both Limit-Offset and Cursor-based are supported.
Runtime for fulfilling API calls:
GraphQL resides on the server between the application backend and the client service whether it be a desktop, mobile device or anything else. You will need a GraphQL server such as graphql-yoga or apollo-graphql/apollo-server and and ORM like Prisma or
Downsides of GraphQL:
Complexity of setup — All queries need to be defined on the backend before they are usable by a client. Often API calls just deal with data in one model and can be streamlined to assume that scope. In GraphQL, each field that can be queried or displayed must be specifically defined. There can be some level of duplication if you want to use the same data in more than one way. There is flexibility but it does come at the cost of complexity.
Some of these features are easier to set up with 3rd party software of which there are a plethora of options. This can cause an additional level of complexity until new software options are fully understood.
Error handling: http codes do not work. All events return 200.
Bibliography: