Facebook developed GraphQL to rebuilt its iOS and Android apps. What is GraphQL? Is it an alternative to RESTful API or
could it be replaced with it in the future?
In 2012, Facebook decided to rebuilt its iOS and Android applications as native.
Since they started off with the motto “Write once, run anywhere”, they ran into a lot of problems. As the
application gets more complicated, they’ve had performance issues and crashes. For that reason, they needed a
different API approach which leaded them to develop GraphQL and they released it in 2015. Well, let’s see what is
GraphQL and if it can replace the most commonly used RESTful API in client and server communication.
GraphQL offers a good way to design and use APIs. Whether it’s an alternative to RESTful or could it be replaced
with it in the future, we will see. But it is possible to say that GraphQL has already been used by many companies.
The most well-known companies among them are Facebook -of couse- along with Twitter, Airbnb, Github and Pluralsight.
We also use graphQL at Cimri.com. One of the reasons we chose GraphQL
was that there are too many endpoints in the REST structure and if the client wants to get certain data, a new
endpoint has to be created again.This situation can get more and more complex in large-scale applications.
GraphQL enabled us to get rid of complex endpoints and access the desired data on the client-side allowing us to
speed up things with ease of use and maintenance as well as better developer-friendly codes.
Table of Contents
REST API VS GRAPHQL API
Based on the picture above, both of them primarily use the HTTP protocol to create APIs.
REST is an architecture style for designing networked applications. GraphQL is a query language developed to improve
performance and usability.
Data fetching: I think this point is the most interesting feature of GraphQL. Because in the REST
API, we may have to send requests to too many endpoints in order to get the data we want. GraphQL provides a single
endpoint to access the data on the server.
In the RESTful API, I assume that when you send a request to the server through the client, we know that it returns
an object or send an object according to the type of the request (get, post, put, delete). This is where the GraphQL
client-side comes into play. When you make a request, you can specify the object you want and which properties of
that object you want to access, and you can make requests accordingly. Since the server creates a design according
to it, it responds to what you want.
Versioning: Whenever there is a change in the REST API, you use the versioning method to indicate
those changes. For this, you may need to check frequently the API you use. GraphQL links the required and requested
information so that it is included when changes occur.
Error Management: You can manage errors by examining HTTP status codes in REST API. But in GraphQL
you will always see 200 (OK) status and you may have trouble managing errors. By using GraphQLError, you can define
errors and trigger these errors in resolvers. You can also return the errors array in your responses by using
Apollo-Server.
Document: While creating the REST API, you need to create the API documentation by yourself. With
Swagger, you can create a configuration and prepare your documentation. But in GraphQL you don’t need to prepare a
documentation. GraphiQL provides a docs and playground environment for you. It creates a diagram and documentation
with the queries you write, and you can run the query you want with the playground it provides and see what it
returns.
Caching: Since We can only “POST” requests from the client to the server in GraphQL, we may have
difficulties in caching. Because we are sending a POST request, the proxy cannot analyze this request. All we have
to do is sending the information into the body. Separating the client and the server can also be an alternative to
solve this problem.
If you are developing applications using the React library, you can use open-source frameworks such as Apollo GraphQL (Data Graph Platform) to solve problems
like caching and error management.
Apollo can simplify communication between server and client providing you with easier solutions instead of using
Redux while making state management, as well as allowing you to write less code. If you want to examine there is
also Relay as an alternative to Apollo.
Now let’s deep dive into GraphQL and take a look at how it is used.
GraphQL SDL
Defining the schema with GraphQL SDL (GraphQL Schema Definition Language) helps you to create the docs and the
schema presented by GraphQL or GraphQL Playground, and to better understand the document.
|
1 2 3 4 5 |
schema { query: Query mutation: Mutation } |
Data Types
GraphQL also has 5 build-in scalar types: Int, Float, String, Boolean and ID. Of course we are not limited to these
5. It can also be field type, object type and enumeration type.
GraphQL Components
It allows us to make separate definitions on client and server sides in our project. On the client side these are
Queries, Mutation, Fragment. On the server side, it is possible to separate them into Type Definition, Query
Definition, Mutation Definition, Resolvers, Composition and Schema.
Supposing that we are making a Todo application, let’s see how we define GraphQL components.
GraphQL supports languages such as Scala, JavaScript, Ruby and many more. Here I will develop the project with
JavaScript.
Type Definition
|
1 2 3 4 5 6 7 8 9 10 |
// Server var { buildSchema} = require('graphql'); var schema = buildSchema (` type Todo { id: String text: String completed: Boolean } `); |
Here, we can define the schema definition and define the object and its properties to be included in the schema.
Thus, we enable GraphQL to prepare more reader-friendly docs.
Queries
|
1 2 3 4 5 6 7 8 9 |
//Client query todos { todos { id text completed } } |
We have defined the objects and properties we want to get from the server. Under the object of Todos, we actually
say that “I want this information of that Todo object”.
Mutations
|
1 2 3 4 5 6 7 |
// Server type Mutation { createTodo(text: String!): String removeTodo(id: String!): String updateTodo(id: String!): String } |
We made our definition of mutation on the server side. We can think of it as create, update, delete operations in
Mutation Rest API. Also, you can create accounts, generate tokens or get your data from input.
We specified our mutations on the client side. Pay attention to the exclamation mark at the end of String!.
It means we expect the server to return a non-empty value. If it returns empty, execution error would be triggered.
Resolvers
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
const resolvers = { Query: { todos: () => todos }, Mutation: { createTodo: (parent, args, context, info) => { return todos.push({ id: Date.now().toString(), text: args.text, completed: false }); }, removeTodo: (parent, args, context, info) => { for (let i in todos) { if (todos[i].id === args.id) { todos.splice(i, 1); } } return args.id; }, updateTodo: (parent, args, context, info) => { for (let i in todos) { if (todos[i].id === args.id) { todos[i].completed = !todos[i].completed; } } return args.id; } }}; |
In Resolvers, we perform our operations for each component we define in the diagram. It can be used to send data to
the resolvers database, to access the data or to make requests to the third-party APIs.
Fragments
|
1 2 3 4 5 6 |
// Client fragment Daily on Todo { text completed } |
It is used to define data pieces that you may want to use more than one.
|
1 2 3 4 5 6 7 8 |
// Client query GetTodo { todo(id: "3"){ ...Daily issueImage(size: LARGE) } } |
As understood from the code above, we can define the data we want to use in more than one place as fragment and then
use it wherever we want with the spread operator (…) in JavaScript.
Subscribers
It is used to establish a real time connection with the server. In most cases, it enables the client to receive a
certain data in real time. It is a very useful feature especially for stock exchange or instant messaging
applications.
|
1 2 3 4 5 |
// Server type Subscription { newTodo: Todo } |
In our scenario, let’s say we want to receive the added new Todos instantly. With the subscription we created, we
create the WebSocket connection so that the server can send updates to the client continuously.
|
1 2 3 4 5 6 7 8 |
// Client subscription { newTodo { id text } } |
Directives
It allows us to organize our queries and create conditionals according to the parameters received. We create
directives by defining them with the @ sign.
|
1 2 3 4 5 6 7 8 9 10 |
query todos($days: Boolean) { todos { id text ucText: text @uppercase // text'in büyük harf dönmesini sağlar. days @skip(if: $days) //eğer false ise days döner days @countinue (if: $days) // eğer true ise days döner } } |
We learned the information we need to know on the basis of GraphQL.
Let’s try sending requests with GraphQL using the Rick and Morty API.
I developed this project with React.js, so I created a project with create-react-app. I decided to use Apollo Client
on the front-end of this project.
Let’s include GraphQL and Apollo client in our project.
|
1 2 3 4 |
npm install graphql --save npm install @apollo/client graphql |
We normally use state management to manage data. Redux, MobX, Context API, and Recoil are state managemenent
libraries for React. But Apollo Client has management that will help us manage the data we will use, and
apollo-link-state will exactly provide us with that. But I used apollo-boost in the project. Apollo boost includes
apollo-link-state, but it allows us to transmit data to client state instead of transmitting it over the link.
Apollo Client 3 came out this July and some improvements have been made. For example, I read that it
handles in itself without downloading apollo-link-state into your project. For further details, check the link
below:
[https://www.apollographql.com/docs/link/links/state/#with-apollo-boost](https://www.apollographql.com/docs/link/links/state/#with-apollo-boost)
Now let’s run this command in our project:
npm i apollo-boost
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
import React from "react"; import ReactDOM from "react-dom"; import "./index.css"; import App from "./App"; import * as serviceWorker from "./serviceWorker"; import ApolloClient from "apollo-boost"; import { ApolloProvider } from "@apollo/react-hooks"; // Apollo Client 3 de ApolloProvider apollo/client içinde geliyor. // Yukarıdaki @apollo/react-hooks a ihtiyacınız yok. // import { ApolloProvider } from "@apollo/client" bu şekilde import edebilirsiniz. const client = new ApolloClient({ uri: "<https://rickandmortyapi.com/graphql/>" }); ReactDOM.render( <ApolloProvider client={client}> <App /> </ApolloProvider>, document.getElementById("root") ); serviceWorker.unregister(); |
Here we see index.js in the project created with create-react-app. We’re importing ApolloClient and ApolloProvider.
Rick and Morty API supports GraphQL, so we can send a request to the URL it gave us thanks to Apollo Client.
Provider will allow us to send the response from the API we request to our React components. As Apollo has in its
own document, this ApolloProvider has a client props and we connect our external API to this props.
Let’s go to App.js, which we wrapped with ApolloProvider.
There is a playground in here, you can learn about
the API by checking the document and schema created by GraphQL.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
// App.js import React from "react";import "./App.css"; import { useQuery } from "@apollo/react-hooks"; import { gql } from "apollo-boost"; //import { gql, useQuery } from '@apollo/client'; //Apollo Client 3 de bu şekilde kullanabilirsiniz. const rickandmorty = gql` { characters { results { id name image gender species } } } `; function App() { const { loading, error, data } = useQuery(rickandmorty); if (loading) return |
Loading…
|
1 |
; if (error) return
|
1 |
Oppss !!
|
1 |
; const newData = data.characters.results; return ( <div className=”container”> <h2
className=”title”>Rick and Morty API with GraphQL</h2> {newData.map((item) => { return ( <div
key={item.id} className=”card”> <img src={item.image} alt=”RickandMorty” /> <div
className=”container”> <div className=”container-title”> <h3 style={{ width: “150px” }}>
<b>{item.name}</b> </h3> <p>{item.species}</p> <p>{item.gender}</p>
</div> </div> </div> ); })} </div> ); } export default App;
|
1 |
The useQuery we import enables us to run the queries we have defined, and at the same time returns loading, error,
data objects that we can use in the client.
GQL, on the other hand, is being used to create our query; then we fill the fields we want to include in the
payload.
Later, we take the information we defined on the query side from the data returned and we print it on the screen.
Actually sending requests to the external API is that simple. GraphQL and Apollo handled most of the things we had
to do.
If you want to check the source code;
https://github.com/Ulubayam/apolloClient
When we run the project, we expect such a page to appear:
https://rickandmortywithgraphql.herokuapp.com/
You can also review the source codes of the Todo application I mentioned above. It was developed by using Apollo
Client and Apollo Server.
https://github.com/Ulubayam/TodoAppWithApolloClient
For GraphQL Server, there is also graphql-yoga as an alternative to Apollo Server. You can check it if you want:
https://github.com/prisma-labs/graphql-yoga
Conclusion
To summarize, according to the researches made by most companies using GraphQL, they stated that GraphQL accelerated
the development process, that their projects could scale faster, their performance increased, they encountered fewer
errors and the architecture became healthier.
If we talk about the disadvantages, the ecosystem is new and developing. If you are going to install a caching
system, you have to use a client library and if you have a distributed structure on the server side, things may
become more complicated for you.
You can also subscribe to GraphQL’s weekly newsletter:
https://www.graphqlweekly.com/
Resources
https://www.apollographql.com/)
https://graphql.org/graphql-js/
https://blog.graphqleditor.com/why-you-should-try-graphql/
Podcast: Null Podcast
