Comparing Rest vs GraphQL on performance and ease of use
Representational state transfer, popularly known as REST, is all the rage these days. First described in Roy Fielding’s seminal dissertation in 2000, the REST specification as become the de facto standard by which applications work with data exposed by APIs that run on the Internet. It seems as if every major information source, from the SpaceX to the FDIC, publishes a REST interface
REST is easy to work with. You make an HTTP GET call to a URL that represents a collection of data entities, a.k.a resources, and you get back data in a well known format, such as XML or JSON.
Also, REST allows you to add data, provided of course you have permission to do so as provided by the API publisher.
However, for all the benefits that REST provides, it has a problem: The caller has no control over the structure of the data an API returns. The immutable nature of REST data structures has performance implications.
GraphQL vs REST performance
Take a look at JSON in the example below (Listing 1). It’s an excerpt of a REST call to the SpaceX API that gets a list of all landing attempts. The URL used to make the call is:
https://api.spacex.land/rest/landpads
This excerpt is a single landing attempt extracted from an array of landing attempts that was returned from the REST call.
{ "attempted_landings": "3", "details": "SpaceX's first east coast landing pad is Landing Zone 1, where the historic first Falcon 9 landing occurred in December 2015. LC-13 was originally used as a launch pad for early Atlas missiles and rockets from Lockheed Martin. LC-1 was later expanded to include Landing Zone 2 for side booster RTLS Falcon Heavy missions, and it was first used in February 2018 for that purpose.", "full_name": "Landing Zone 2", "id": "LZ-2", "landing_type": "RTLS", "location": { "latitude": 28.485833, "longitude": -80.544444, "name": "Cape Canaveral", "region": "Florida" }, "status": "active", "successful_landings": "3", "wikipedia": "https://en.wikipedia.org/wiki/Landing_Zones_1_and_2" }
Listing 1: A JSON object that an element in a collection of landing attempts returned by a call the SpaceX REST API
REST, JSON, speed and verbosity
The nine properties displayed in the JSON above are immutable. As a caller, I can’t tell the REST API to give me only the full_name and wikipedia data. No matter what, whether the REST API returns a single landing attempt or a thousand landing attempts, I am always going to get those nine properties.
This might not seem like a big deal, but it is. If I could make REST only return the two fields of data that are interesting to me instead of the nine that I will always get, the returned data set would be considerably smaller. Not only does REST ensure that a lot of uninteresting data makes its way over the network, but that uninteresting data sits in memory on the client side. There’s an intrinsic inefficiency at hand.
Wouldn’t it be cool if there was a way to query an API for data according to a data structure you define, asking only for the data you want, as you want it? Fortunately, there is and that way is not REST. It’s GraphQL.
When you compare REST vs GraphQL, performance is a critical criteria — and here GraphQL outshines REST and JSON.
Simplified REST with GraphQL
GraphQL is an API architecture first developed at Facebook 2012, and released to the public in 2015. Since 2018 it is supported by the GraphQL Foundation, which is hosted by the Linux Foundation.
GraphQL specifies a query language that allows a developer to call a GraphQL-enabled API and get data returned according to a data structure defined by the GraphQL query.
Take a look at the example below (Listing 2). It’s a query that will run against the same land pads data published by the SpaceX REST API used earlier in this article. This time, though, its a GraphQL query made against the SpaceX GraphQL API, which is published at https://api.spacex.land/graphql/. The query declares that it’s only interested in two fields: full_name and wikipedia.
{ landpads { full_name wikipedia } }
Listing 2: A GraphQL query against the SpaceX GraphQL API for all landing attempts by full_name and wikipedia URL
REST vs GraphQL JSON exchanges
The data below in Listing 3 is the result of the GraphQL query shown above in Listing 2.
{ "data": { "landpads": [ { "full_name": "Landing Zone 1", "wikipedia": "https://en.wikipedia.org/wiki/Landing_Zones_1_and_2" }, { "full_name": "Landing Zone 2", "wikipedia": "https://en.wikipedia.org/wiki/Landing_Zones_1_and_2" }, { "full_name": "Landing Zone 4", "wikipedia": "https://en.wikipedia.org/wiki/Vandenberg_AFB_Space_Launch_Complex_4#LZ-4_landing_history" }, { "full_name": "Of Course I Still Love You", "wikipedia": "https://en.wikipedia.org/wiki/Autonomous_spaceport_drone_ship" }, { "full_name": "Just Read The Instructions V1", "wikipedia": "https://en.wikipedia.org/wiki/Autonomous_spaceport_drone_ship" }, { "full_name": "Just Read The Instructions", "wikipedia": "https://en.wikipedia.org/wiki/Autonomous_spaceport_drone_ship" }, { "full_name": "A Shortfall of Gravitas", "wikipedia": "https://en.wikipedia.org/wiki/Autonomous_spaceport_drone_ship" } ] } }
Listing 3: The result of a GraphQL query made against the SpaceX GraphQL API
Only the full_name and wikipedia data is returned. This is the data the developer wanted, no more and no less. The actual size of the GraphQL is 1.09 KB. When we ask the SpaceX REST API for the land pad data, the size of the JSON array returned is 8.18 KB. Remember, the REST API has to return all the fields, all the time. The efficiency GraphQL provides is apparent.
GraphQL vs JSON performance analysis
REST is a very popular API architecture and is not going away anytime soon. REST provides a degree of standardization that makes working with public APIs an easy, commonplace occurrence. There were other API architectures before REST came along, for example SOAP, but REST’s simplicity made it hard to ignore. Arguably, REST was the engine that drove the early days of the API adoption. Nevertheless, REST comes with overhead, as demonstrated above.
GraphQL, the new kid on the block, already enjoys wide-spread adoption. A lot of big names are behind GraphQL, including the NY Times, JPMorgan Chase, PayPal and Bank of America to name a few.
GraphQL offers a lot of flexibility for data management. Also, the way GraphQL conceptualizes data under its hood is more in line with the principles of the Semantic Web. The Semantic Web is a way to think about all the data on the Internet in an infinite amount of, but concretely describable, relationships.
Nonetheless, both REST and GraphQL are here to stay. As such, understanding the details, benefits and tradeoffs of each API architecture is useful knowledge for developers working in the API economy.