Skip to main content
Blog API

Decoding GraphQL API

Devi M
July 13, 2022 |
Your guide to GraphQL

In this article, let us understand the basics of GraphQL, its components, operations as well as:

What is API? What are its types?

Let me start with what an API is and its architecture types. An API or Application Programming Interface is a software intermediary which allows two applications to interact with one another. Any time we use an app in mobile or browser like social media or eCommerce we’re actually sending an API request to the server.

There are three types of API architectures: REST, RPC, and SOAP.  The REST API which is Representational State Transfer means when it is called, the server will transfer a representation of the requested resource’s state to the client system. REST API is most commonly used for data fetching.

While SOAP (simple object access protocol) surfaces actual application logic through a different set of interfaces, it’s ideal for performing operations. SOAP relies heavily on XML, and with schemas, defines a very strongly typed messaging framework.

On the other hand, RPC APIs invoke processes or execute scripts on a server. It is a relatively simple and easy way to execute code on remote networks, hence can be used for internal systems to make basic process requests.

What is GraphQL?

GraphQL is considered an alternative to REST APIs. GraphQL can be defined as a declarative query language and a runtime that is used to request data on a server. It provides an understandable description of the data in your API, thereby providing clients with the ability to define and ask for exactly what they want and nothing more or less. GraphQL simply means seeing the data as a graph and then querying that graph.

History

GraphQL was designed by Facebook in 2012 to solve the problems they were experiencing with their mobile applications. 

They wanted an alternative for REST API which has data-fetching enough to accommodate all Facebook’s data, that is easy to understand. It was implemented in their mobile app in 2012 and open-sourced in 2015.  This query language has proven to be useful for developing modern web and mobile apps and is rapidly becoming the standard for API-based data access. 

Programming languages that support GraphQL server are JavaScript, Perl, Python, Ruby, Java, C++, C#, PHP, and more.

Application Components

Server-side components: Server-side components allow to parse queries that are coming from the client applications. It uses 3 main components which reside on the GraphQL Server.

Query: A query is a request from the client application used for retrieving data from the GraphQL server. Any query request from the client will be executed in the GraphQL server and it returns the requested data back to the client as a response.

Schema: It describes the functionality and shape of the available data for the connected clients. It is the server’s API which the client can refer to know what operations can be performed on the server. It defines the root operations like queries, mutations, and subscriptions with its properties declared as types and fields.

Resolver: The functions or execution algorithm which transforms the query from the client to the actual response is defined as the Resolver function of GraphQL.This function will accept four input arguments which are parent, args, context, and info. 

Client-side components: The client-side components reside on a GraphQL Client. The GraphQL client is a code that mostly makes POST requests to the GraphQL server

Apollo Client: Apollo client is one of the best graphQL client applications that is used for JavaScript front-ends. It has the benefits of dealing with network traffic by normalizing the data and also caching the client requests. Other advantages like prefetching data pagination and supporting a layer of connection between the data layer and the view layer also make it more popular.

GraphiQL – It is a browser-based interface used for running GraphQL queries and mutations which is mainly used by developers.

GraphQL primary operations:

Operations are executable actions within a GraphQL document. There are three types of operations in GraphQL: Queries, mutations, and subscriptions. The main operation requests are Queries and Mutations.

  1. Query for reading data – They do not change the state of the data, it will return the result only. It is used to find a starting point and traverse a subgraph
  1. Mutation for writing data. It is used to modify server-side data. Create, update and delete operations of data are done using mutation. They change the graph and return a result.
  1. Subscription for automatically receiving real-time data over time.GraphQL subscriptions are made majorly to listen to when data is created on the server, when data is updated, when data is deleted, and when data is read via query. GraphQL uses an Event-based approach to implement its subscription operation. The client subscribes for events to the server and the server informs the client whenever any event is triggered. It is used to listen for changes in the graph

How GraphQL Works

Here are the three steps the server takes to respond to any query:

Step 1: Parsing the query

The query which is stored as a string is parsed and converted into an AST — an abstract syntax tree. The GraphQL.js validate function will traverse the tree to check for any syntax errors using depth-first traversal and return the errors to the client.

Step 2: Validation

A query that is syntactically correct may sometimes still make no meaning if its operation is not well defined 

GraphQL Validation

The schema plays a vital role between the client and the server by defining how to access the data.This step makes sure that the query is sound as per the schema before execution starts. It checks things like:

  • is country a field of the Query type?
  • does country accept an argument named id?
  • Are available_regions and full_name_english fields on the type returned by country?
  • … and many more …

As an application developer, we no need to worry about this part, because the GraphQL server does it automatically. But in RESTful APIs, it’s the developer who has to make sure that all the parameters are valid.

Step 3: Execution

After successful validation, the GraphQL server will execute the query. All GraphQL query is tree-shaped whose execution begins at the root of the query. First, the executor calls the resolve function of the fields at the top level — in this case just country — with the provided parameters. The server will wait until all the resolver functions return a value, and then proceeds in a cascading fashion down the tree. Same way, if any resolve function returns a promise, the executor should wait until that promise is also resolved.

Characteristics

GraphQL has several notable characteristics:

  • It allows the client to specify and get what they need
  • It allows for resources via a single request
  • It uses a type system instead of endpoints to describe data –  The schema serves as a contract between the server and the client to define how a client can access the data.
  • Once the schema is defined, the front-end and back-end teams can work independently, as the front-end can be easily tested with mock data.

Who’s using GraphQL?

GraphQL is used by organizations of all kinds to power mobile apps, websites, and APIs. Here are a few companies that do so:

Organizations using GraphQL
Devi M

Devi is a Senior Software Engineer with 7 years of experience in the IT industry. She has experience as a senior test associate, and full-stack developer in various sectors including health care, networking, and eCommerce. She is also a yoga enthusiast who loves to try new recipes and play with kids.

More posts by Devi M