Every once and awhile a technology or application development paradigm comes along that really changes the way you think about building web apps. GraphQL is one of those technologies.

GraphQL is the most recent application development tool to be open-sourced from Facebook’s internal libraries and tools. GraphQL stands for graph (as in, graph database) query language. GraphQL is not a specific framework, library, or tool, but rather a specification with implementations in several popular languages. There is an official reference implementation written in Javascript, and popular libraries for Ruby, Java, Python, and PHP to get up and running quickly.

To understand the value provided by GraphQL, first, examine the currently predominant ways to exchange data between web servers and web or mobile applications.

The Traditional Approach

The classic, and most common approach, is to pre-render HTML on the server and send the HTML to the client. This works very well for all websites that require no real time interactivity.

The Hybrid Approach

A step up from that approach is the hybrid approach. The server pre-renders HTML which the client renders, then certain components of the page are made more interactive with sprinklings of Javascript, typically using jQuery and REST endpoints.

The Modern/SPA Approach

Next are apps that typically use frameworks like Angular, Ember, React, or another all-inclusive front end framework. Applications that use these frameworks are typically blank without Javascript support, and don’t load any application data or state inside the HTML. To accompany this, the server needs to implement some mechanisms, such as REST or an RPC API like JSON-RPC, to send the client the data it needs to render the application. Building an app using this type of design comes with the cost of increased complexity, but also the advantage of enabling highly reactive and potentially real-time user interfaces.

The most common choice for building a web application these days is to obtain your data through a series of rest endpoints. You may have a /users/ endpoint for getting data about users, a /users/{userId} endpoint for getting data about a specific user, /users/{userId}/timeline endpoint for getting a user's timeline data, and so forth.

This architecture has some advantages. It’s simple, the concerns of each endpoint can be separated cleanly, and it’s easy to add new endpoints and features without breaking the compatibility of existing endpoints. However, it also comes with many disadvantages that become more apparent as the surface area of the API grows.

One of the primary issues with normal REST paradigms is that the client normally has limited or no ability to request a limited subset of data. You either get all the fields for a given user or none. In most traditional REST interfaces, asking for a limited or expanded subset of data is tricky and awkward.

Another issue relates to the growing pains of having multiple endpoints to maintain. Endpoint bloat can occur as the app grows, where clients often need to request data from 5+ different endpoints in order to have a complete picture of the data they need to render the page. GraphQL offers a simple and elegant solution.

The GraphQL Approach

When building a GraphQL server, you only have one URL/endpoint for all data fetching and mutating. A client can request a set of data by sending a query string to the server that describes the data they want. A typical query for a user would look like this.

{ user(userId: “123”){  firstName  lastName  posts {    _id    title  } } }

This query may return a JSON object that looks something like this

{ "user": { "firstName": “John", “lastName": “Doe", posts: \[{"\_id": “1", “title": “GraphQL is pretty cool"\]} }

If a user needed a different subset of data, they could send a different query string to the server and the server would return a result reflecting that request.

``` {  user(userId: “123”){  firstName  posts {    _id    title    body  } } }

returns { "user": { "firstName": "John", posts: [{"_id": "1", "title": "GraphQL is pretty cool", "body": "post body .. ."]} } ```

Because of this clean, succinct, and powerful query language, GraphQL is able to provide many advantages over traditional REST endpoints.

• Because of the Graph structure exposed through GraphQL, interweaving data from various sources behind the scenes to form a single schema is often easier to implement and utilize than managing separate REST endpoints.
• Developing for a range of different clients is far easier than with a REST structure. Rather than developing separate, but similar, endpoints to handle different client’s data needs, or having to manage larger more awkward endpoints, you can include all your data in a single schema and each client can request exactly the data they need.
• Introspection. GraphQL servers are required to expose details about the structure of their data. Internally, we use these “introspection queries” as part of our testing process to guarantee that our schema changes won’t break compatibility with old clients. The community has utilized these introspection queries to build GraphQL API explorers (GraphiQL!) and auto-generated Admin interfaces.
• Abstracting shape of application data from actual implementation of data fetching and storage. Writing a GraphQL schema necessitates separating the concerns of sending data from the concerns of loading data. Identify this abstraction and focusing on it has allowed our team to mock data easily when developing a new feature, as well as easily migrate data fetching from one source (for example, an external API) to another (a locally cached representation of the external API.)

If you want to play around more with GraphQL requests, check out this interactive playground.

GraphQL hasn’t been around for long, but many larger organizations have already adopted it. Facebook developed the original specification internally and use it for the majority of their applications. Github tried building a new feature in GraphQL and ended up liking it so much that they recreated their existing API in GraphQL and open sourced it. Twitter used GraphQL to scale their dashboard for their SaaS product Fabric.

If you are interested in learning more about GraphQL, you can start by checking out Facebook’s Learn GraphQL. We use Apollo internally to enable rapid iteration on both our application server and React / React Native clients, but your mileage may vary depending on your existing infrastructure and requirements

At Differential GraphQL has provided an incredible tool for rapidly and effectively developing application servers and web/mobile clients that are scalable and easily maintainable. We agree with Github when they say “GraphQL represents a massive leap forward for API development.”