API Pain and GraphQL Relief

October 12, 2018 · by Jeff Costa ·

If you talk to enough API developers, you start hearing very similar stories about API pain points. It doesn’t matter what industry you work in, what the client is, or what language you write in - the misery cuts across all of it. This blog post reviews some common pain points with RESTful APIs, and how GraphQL helps address them.

As part of my job as a product manager at Akamai, I’m constantly talking to customers and learning about their API ecosystems. The use cases for the APIs they build are diverse: site personalization, mobile apps, in-store kiosks, hotel reservation systems, weather data, gaming - to name a few. Regardless of what they are building or the client that consumes their API, I hear certain problems over and over:

  • I don’t know how my API is being used. I know my API is being used - I just don’t know which part of it. What do my API consumers use and what do they simply not care about? This goes beyond aggregated request counts and usage patterns. I need to know where to direct future investments and development hours.

  • My front-end devs move fast, but backend works slows us down. We know that iterating quickly is a competitive advantage. My front-end teams are racing to support lots of platforms to be where our users are (mobile, web, voice). But they always seem to be stymied behind the backend work of building custom endpoints to meet our ever-changing client needs.

  • Every action needs a corresponding endpoint. My APIs always start out simple and generic. But when I look at them today, I can’t believe how long our query strings have become. We seem to be writing our own query language as features get tacked on over time. It makes the whole thing complex and fragile.

  • Love/HATEOAS. We do REST right - which means hypermedia to navigate our REST interfaces dynamically by including links with our responses. Putting six requests on the wire helps our clients find and obtain the data they need. Or does it?

  • Payload bloat. When I send data down to the client, I often have to paginate because there is just so much of it. If I sent it all down - it would likely kill the client. Just don’t ask me how much of that payload is actually used - and how much is thrown on the floor.

  • Documentation. We can never keep our documentation aligned to our API. Swagger certainly helps, but no developer likes to write documentation. Our docs seem to always be one step behind our code.

  • Discovery. There is this ONE part of our API we thought would be crazy valuable and the most popular feature we ever built. It barely gets used because nobody can find it.

If you're building a RESTful API today, then these should sound familiar. Unfortunately, REST does not meet many of the challenges faced by modern development teams. REST’s defining feature is its ability to reference resources, but problems happen when these resources require (repeated) round trips between the client and server. As web developer Kristopher Sandoval put it: “What this ultimately results in is a system where the more useful it is, the slower it is. In other words, as more relational data is presented, the system chokes on itself.”

There are alternatives, notably the GraphQL query language that addresses many of these problems. GraphQL is an open source data query and manipulation language that was developed by Facebook and publicly released in 2015. Let's look at how GraphQL addresses these problems:

  1. Analytics: A GraphQL request is a query that can be tracked to see how many times it was used in a single day. You know what data is used - and deprecate what isn’t.

  2. Decoupling: The frontend has been liberated from the backend. Gone are the days of back-and-forth with backend teams to build the queries needed to surface data in the UI. Front-end teams can specify the exact shape of the data they get back, making them more nimble and efficient.

  3. Single Endpoint: GraphQL operates from a single /graphql endpoint. No discovery issues. No separate web and mobile URLs. Reduced complexity.

  4. Interactive Documentation: Documentation is always in sync with implementation. Developers using GraphiQL or Playground get “just in time” documentation for the query they are building. No more neck pain from looking at API docs on one monitor and code on the other.  

  5. Payload Reduction: GraphQL was designed for performance, letting the client declare just the data it needs - no more and no less.

GraphQL is not a panacea. If you control both the client and server, you tend to love GraphQL. If you only control the server and your customers control the client, you might hate GraphQL because it's too powerful.

Akamai believes GraphQL is a potent alternative to REST where performance and developer productivity matter most. In a span of 6 months, the number of companies with GraphQL APIs on the Akamai platform increased by 68%. We expect it to live side-by-side with REST, and are making investments to support this technology.

The first thing you’ll see from us in this space ties into what we do best: caching. Caching is notably absent from the GraphQL specification, but is still a necessary component for API scalability.

We recently entered beta with a new capability in our API Gateway product: full query caching. We can now canonicalize GraphQL queries (requests) by removing whitespace, differential properties, property order, and more in order to compute a unique cache key for the object at the edge.

Graphql user interface

This is only a start, but we think the future of GraphQL is bright, and know we have more to build. If you would like to try this new technology, please reach out to your Akamai account team to gain access.

Jeff Costa is a senior product manager at Akamai Technologies.