GraphQL for Dummies

Web technologies they can seem quite mystical to people who are not initiated to them. GraphQL is a popular buzzword and a common term in the web development circles in 2016. While there is quite a bit of underlying complexity, the basic concepts and advantages can be summarized quite fast.

GraphQL is a technology that originates to Facebook in 2012. It is a technology that is used for communications between the server and clients. If you are familiar with concepts from REST, it is a similar technology. The main difference is that it's a clear, open specification where REST is an ambiguous term.

APIs in general are endpoints that allow computer programs to talk to other applications. There are internal APIs that are available inside individual applications, but on the web development terms people mostly mean public APIs. These are interfaces that are open to external applications through the internet.

The reason for the rising popularity of GraphQL is that thought by many to be a great way to create open web APIs. There has been a lot hype around GraphQL, but the possibilities and points are easily lost in the jargon. In general some characteristics of a good API are:

  • Good APIs are fast. The more data you have to juggle around in a public environment like the Internet, the more delays you get. Mobile applications are especially vulnerable due to the physical limits of communications over air.
  • Good APIs don't change. APIs are meant to be consumed by other applications. When you do changes to your application you want to be sure the endpoint you are calling behaves in a consistent way. An API should never drop or change old behaviour without prior warning in due time.
  • Good APIs are nice to use. Creating a unique technology is increasingly hard. For developers the choice between two identical technical tools is made largely based on the documentation and tooling availability. It's very frustrating to work with a technology that is unclear.

GraphQL as a technology standard and as an ecosystem performs very well on all three fronts. With the possibility of easily aggregating all required data to a single request provides best possible performance over mobile networks for example.

With GraphQL being in development and production for over five years means that it is robust and predictable - this is thanks to Facebook using it in production on a large scale for years prior to publishing the standard in 2015. In addition the strong typing of GraphQL means that you can always expect to get the answer back in a specific format.

For what is an eternity in web development the best thing for creating APIs was Representational State Transfer, more commonly known as REST. RESTful APIs are in many places, but it falls behind GraphQL in the three characters a good API should have:

  • REST APIs have the tendency to be very limited in their delivery. This makes them slower in real life applications, where as GraphQL natively aggregates different data to a single request.
  • All REST APIs need to be versioned with skill. A REST API found from a certain URL is often a volatile option. With GraphQL the address is always the same, but the request shapes the request - this makes it possible to add new fields.
  • Having a REST API is a very loose statement. It gives an idea on how the API is created, but documentation and tooling is always very specific to individual APIs.

So by definition REST is not inferior to GraphQL, but it does not enforce conventions. This leads to a lot of undesired diversity in projects and tools that have REST APIs. If you are working with a headless CMS implementation, you are essentially coupling yourself tightly to a specific REST API.