Rest vs GraphQL: Performance and Usability Comparisons

0

Representative State Transfer, popularly known as REST, is all the rage these days. First described in Roy Fielding’s seminal work thesis in 2000, the REST specification became the de facto standard by which applications work with data exposed by APIs that run on the Internet. It seems every major news source, from SpaceX to the FDIC, publishes a REST interface

REST is easy to use. You make an HTTP GET call to a URL that represents a collection of data entities, i.e. resources, and retrieve the data in a well-known format, such as XML or JSON.

Additionally, REST allows you to add data, provided of course that you have permission to do so, as provided by the API publisher.

However, despite all the advantages provided by REST, there is a problem: the caller has no control over the structure of the data returned by an API. The immutable nature of REST data structures has performance implications.

GraphQL vs. REST performance

Take a look at the JSON in the example below (Listing 1). This is a snippet of a REST call to the SpaceX API that gets a list of all landing attempts. The URL used to place the call is:

https://api.spacex.land/rest/landpads

This snippet is a single landing attempt taken from an array of landing attempts returned by 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 item in a landing attempts collection returned from a call to the SpaceX REST API

REST, JSON, speed and verbosity

The nine properties shown in the JSON above are immutable. As a caller, I can’t tell REST API to only give me full_name and wikipedia data. Either way, whether the REST API returns a single landing attempt or a thousand landing attempts, I’ll always get those nine properties.

This may not seem like a big deal, but it is. If I could make REST return only the two fields of data I’m interested in instead of the nine I’ll always get, the returned dataset would be considerably smaller. Not only does REST ensure that a lot of uninteresting data flows across the network, but that the uninteresting data stays in memory on the client side. There is 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, requesting only the data you want, however you want it? Luckily there is and this path is not REST. It’s GraphQL.

when you compare REST vs. GraphQLperformance is critical – and here GraphQL outperforms REST and JSON.

Simplified REST with GraphQL

GraphQL is an API architecture first developed in Facebook 2012 and made public in 2015. Since 2018, it has been 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 compatible API and get data returned according to a data structure defined by the GraphQL query.

Take a look at the example below (Listing 2). This is a query that will run against the same terrain data published by the SpaceX REST API used earlier in this article. This time, however, it’s a GraphQL query made against the SpaceX GraphQL API, which is published at https://api.spacex.land/graphql/. The query states that it is 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 URL wikipedia

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 performed on the SpaceX GraphQL API

Only full_name and wikipedia data are returned. This is the data the developer wanted, no more, no less. The actual size of GraphQL is 1.09 KB. When we ask the SpaceX REST API for terrain data, the JSON array size returned is 8.18 KB. Remember that the REST API should return all fields, all the time. The efficiency provided by GraphQL is obvious.

GraphQL vs JSON performance analysis

REST is a very popular API architecture and isn’t going away any time soon. REST provides a degree of standardization that makes working with public APIs easy and common. There were other API architectures before REST came along, for example SOAP, but the simplicity of REST made it hard to ignore. Arguably, REST was the engine that drove the early days of API adoption. However, REST comes with an overhead, as demonstrated above.

GraphQL, the newcomer, is already enjoying wide adoption. Many big names are behind GraphQL, including the NY Times, JPMorgan Chase, PayPal, and Bank of America to name a few.

GraphQL offers great flexibility for data management. Additionally, the way GraphQL conceptualizes data under its hood is more in line with Semantic Web principles. The Semantic Web is a way of thinking about all the data on the Internet in an infinite amount of relationships, but concretely describable.

Nevertheless, 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.

Share.

About Author

Comments are closed.