REST vs GraphQL

When Cherre first started, we had a vision of connecting all real estate data to transform real estate investing and underwriting into a science.  Collecting, standardizing, and connecting such a large amount of data over hundreds of data sets is a massive undertaking.  Cherre’s goal is to enable its customers to access their connected data in the most easy, straightforward, and flexible way possible. We knew that we could not predict all of the ways that our customers would want to use their data so we wanted to future-proof our API. This led us to make some early, very important architectural decisions when we first started connecting data. One of the most important decisions was to make data available as a GraphQL API, which Facebook open-sourced in 2015, versus the more traditional REST API, which has been the standard for most APIs since its formal specifications were released in 2000.

REST API

The World Wide Web exploded in the early 90s. In the beginning, there was a fractured description of what the Web’s architecture should look like and there was a need for standardizing the Web’s protocols for how computer systems communicate, particularly between a client and a server. REST, or Representational State Transfer, is a set of principles for networked-based applications designed to be as lightweight to make adoption as easy as possible.  REST commonly uses HTTP methods such as GET, POST, PUT, and DELETE to access resources through a url and responds with HTML, XML, or JSON.  With REST the client and the server code can be implemented independently of each other.  As long as each side knows what format the messages are being sent back and forth, the code can be developed independently of each other and allow for flexibility and scalability.

Paths

Each request in REST should contain a path to a resource the operation is performed on, and help the client know what is being accessed. For example, if Cherre were to create a REST API it might look something like this:

cherre.com/api/block/{block_id}/buildings

cherre.com/api/building/{building_id}/units

One of the difficult parts of developing with a REST API is that every resource we want to access requires its own route, and requires a developer to write code specifically for each type of resource we want to interact with.  In the example above if we want to get a list of all the units on a block in NYC, we’d first have to get the block ID, and then get IDs of all the buildings on that block.  Now that we have a list of all the building IDs on that block, we can do either one of two things:

  1. We could call the ‘/building/{building_id}/units’ endpoint for each building ID returned. This would require multiple calls to the API and code on the client to aggregate the results together and display them.

OR

  1. We could just have a backend developer write us a whole new route.  This route would accept a list of building IDs and return a list of units for all of those buildings.  It might look something like this:

cherre.com/api/buildings/{building_ids}/units

Enter GraphQL

In this rather simple example, we can see the downside to using a REST API in that we’re limited to the data we can pull based on the routes or paths that have been made available to us.  We have to either make multiple calls to the database, and aggregate the results on the client-side, or we have to have the backend team create a new route for us that accepts a list of building IDs. However, that will still require at least two calls and logic on the client to merge that data.

The more datasets an API makes available, and the more complex the application is, you need more routes to access different resources and you need to make more calls. It becomes a maintenance nightmare. This also assumes the user has access to a broadband internet connection, and the client is running on a laptop or desktop. What if the user is on a mobile device with low bandwidth and reduced response times? These multiple calls from the client to the server are going to slow down the whole user experience. This is where Facebook found itself in 2012 when working on their mobile applications for iOS and Android in 2012.

Imagine you’re Facebook and your main feature is building out and creating a user’s timeline.  Think of all the pieces of information you need to build this. You need to get a list of all the users’ friends, all of those friends’ most recent posts, all of that post’s most recent comments and likes, and any images too. Now imagine you’re doing this on a mobile device in 2010 and you have to make multiple calls in serial to a backend over some crummy 2G connection.  All the while your user impatiently waits for their timeline to load up so they can post a picture of their dog. Yikes! Obviously, something had to be done and that’s when Facebook came up with GraphQL.

GraphQL is a data query language that Facebook developed that provides a way to define a complex data schema and allows a client to ask for exactly what they need and returns it to them in a JSON response. This solved many problems with REST APIs. 

One of the issues GraphQL solves is no longer requiring multiple versions of your REST API.  Facebook had different versions of their API depending on what mobile platform they were developing for, one for iOS and another for Android. This became very frustrating to maintain two separate versions of the API depending on the platform.

Another problem GraphQL solved was being able to get several API responses back in a single request. In the previous REST example of creating a user’s timeline, the client would have to make several API calls to multiple different endpoints in order to get all of the information needed. However, with GraphQL, a single query could return all of the data needed with one call.

Also, a GraphQL allows the client to get back as much or as little data as needed, saving on bandwidth for mobile devices. A REST API call needed for the client might return all of the fields for a given table in the database when really the developer is interested in just one.  GraphQL allows the developer to specify as few or as many fields they want to get back.

Allowing the client side to get back exactly what it needs sped up development time, reduced complexity, and led to a faster user experience for Facebook users. Facebook’s timeline is a perfect example of the kind of rich application you can build with connected data. All the user’s friends, all their friend’s posts, comments, likes, and more, connected are what makes the application so engaging. That’s exactly what Cherre wanted to enable by connecting real estate data. With Cherre’s name and address standardization, we’re able to connect data that normally would not be able to be connected and gain valuable insight into that data.  All in one place in a simple to use GraphQL API.

Dustin Sinkey is a developer at Cherre.