Rethink your API with GraphQL

Rest is the underline architecture of Web and how the clients and servers communicate each other. Using Rest, clients and servers can communicate each other without a prior knowledge. Because of the power of Rest principles, over the time software architects have grabbed the core principles from it to implement APIs in applications. Following are some of the core principles in Restful APIs.

1. It works over HTTP protocol which is stateless
2. The architecture fully operates with the concept of individual Resources which are identified uniquely through URIs.
3. Resources can be manipulated using basic HTTP verbs such as GET, PUT, PATCH...

Since Restful APIs fully focused on individual resources, there are several consequences you'll face other than all the advantages you are getting with Restful APIs.

1. Since the resource manipulation is done through HTTP verbs, the ability to perform complex manipulations containing multiple different types of resources is not straightforward. There may be situations where clients needed to have multiple roundtrips to perform such an operation.
2. In order to manipulate multiple related resources, clients will have to maintain the state between operations through headers or other way.
3. Service discovery and client tooling will be difficult due to lack of a strong type system at back end.
4. Since resource representation should be generic at the API and all the clients will share the same representation, there won't be any control on the amount of transfer data to clients(over fetching).

When it comes to mobile clients, the disadvantages such as multiple roundtrips, over fetching data will be really critical because those are used in low bandwidth environments.

When Facebook has started their mobile apps in 2012, initially they have decided to use a Restful API to communicate with backend services. With drastic development cycles, they have found that many versions of their mobile app are out there in use(one in each two weeks) which calls to the same backend service runs on Rest architecture. This has lead to serious issues on managing and maintaining their API to support different versions of the client apps. A set of engineers at facebook have started to find a new way of overcoming these problems and GraphQL has come out as a result of that effort.

What is GraphQL?

A data query language for client applications defines a flexible way to request and provide data requirements. It allows developers to define the data requirement as same as they think about the data.

Following are some of the main advantages in GraphQL over Restful APIs.

1. Hierarchical: Most product development today involves the creation and manipulation of view hierarchies. To achieve congruence with the structure of these applications, a GraphQL query itself is a hierarchical set of fields. The query is shaped just like the data it returns. It is a natural way for product engineers to describe data requirements.
2. Product-centric: GraphQL is unapologetically driven by the requirements of views and the front-end engineers that write them. We start with their way of thinking and requirements and build the language and runtime necessary to enable that.
3. Client-specified queries: In GraphQL, the specification for queries are encoded in the client rather than the server. These queries are specified at field-level granularity. In the vast majority of applications written without GraphQL, the server determines the data returned in its various scripted endpoints. A GraphQL query, on the other hand, returns exactly what a client asks for and no more.
4. Backwards Compatible: In a world of deployed native mobile applications with no forced upgrades, backwards compatibility is a challenge. Facebook, for example, releases apps on a two week fixed cycle and pledges to maintain those apps for at least two years. This means there are at a minimum 52 versions of our clients per platform querying our servers at any given time. Client-specified queries simplifies managing our backwards compatibility guarantees.
5. Structured, Arbitrary Code: Query languages with field-level granularity have typically queried storage engines directly, such as SQL. GraphQL instead imposes a structure onto a server, and exposes fields that are backed by arbitrary code. This allows for both server-side flexibility and a uniform, powerful API across the entire surface area of an application.
6. Application-Layer Protocol: GraphQL is an application-layer protocol and does not require a particular transport. It is a string that is parsed and interpreted by a server.
7. Strongly-typed: GraphQL is strongly-typed. Given a query, tooling can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at development time, and the server can make certain guarantees about the shape and nature of the response. This makes it easier to build high-quality client tools.
8. Introspective: GraphQL is introspective. Clients and tools can query the type system using the GraphQL syntax itself. This is a powerful platform for building tools and client software, such as automatic parsing of incoming data into strongly-typed interfaces. It is especially useful in statically typed languages such as Swift, Objective-C and Java, as it obviates the need for repetitive and error-prone code to shuffle raw, untyped JSON into strongly-typed business objects.

Following video explains the syntax in GraphQL.

 GraphQL opens up and talk about very powerful stream of concepts which allows us to rethink about our API designs. Even though it won't replace Restful APIs in all the contexts, there is a high chance of immediately dominating how the backends get exposed to the mobile clients.

Following are some resources to learn more about GraphQL.

1. graphql.org
2. learn graphql course
3. videos
4. graphql facebook tutorial
5. schema by kadira
6. slack channel