The ephemeral stack - commercetools: Why GraphQL is the 'glue' for composability
This is a guest post for the Computer Weekly Developer Network written by Kelly Goetsch in his role as chief product officer at commercetools — a cloud-based headless commerce platform that provides APIs to power e-commerce sales and similar functions for large businesses.
Goetsch writes as follows…
Historically, organisations looking to build online experiences went to [insert mega vendor name of choice] and bought essentially a ‘website in a box’.
It worked, but that approach didn’t offer brands the ability to really connect with their customers. The websites (yes they’re typically just websites) offered bland, cookie-cutter templates that are transactional and uninspiring at best. As public cloud arose in the late 2000s and vendors began to offer data and functionality over discrete APIs, what we now know of as composable IT emerged.
There are now thousands of firms that offer one piece of functionality and do it exceptionally well. Taking the example of the commerce sector, functionality components include search, content, personalisation, etc. We have popularised the term ‘composable’ in throughout this last decade to describe the ability for organisations to build a layer of APIs from third-party best vendors and applications built internally. By allowing all of the data and functionality to be accessed over a clean API layer, retailers and brands can then ‘compose’ rich, immersive experiences on any device.
Whether it be a traditional website, smart watch, kiosk, or Internet of Things (IoT) device, APIs are the universal currency in today’s digital world.
A clutch of ‘clients’
Goetsch: APIs are unequivocally amazing, but they are built by and for the producers of the APIs – not the clients that consume the APIs.
Composable IT as a concept is great but it’s not without its challenges. APIs are easy for internal teams and third-party vendors to build and expose but they can pose challenges to clients. A client is what end-users engage with – a website, smartwatch, kiosk, etc. Any device with an Internet connection could technically be a client. Clients all have very different needs, however.
Let’s take a look at a standard product detail page as an example.
For a single product, a client like a website will retrieve dozens of product attributes, product images, product reviews, upsell products, cross-sell products, and more. It’s not uncommon to retrieve multiple megabytes of data to just render one page. Fortunately, that’s not a big deal over a new laptop on a broadband connection.
Now let’s pretend you’re rendering the same page from a mobile app, on a five-year-old smartphone, over one bar of a 4G cellular network. Or imagine a smartwatch tethered to the aforementioned smartphone. Clients all have dramatically different needs in terms of the data they require, processing power, and internet connectivity.
REST API issues
To further complicate matters, APIs, REST APIs, specifically, suffer from some further issues:
- Over-fetching – accidentally requesting too much data from an API. For example, retrieving all 50 product attributes over a smartwatch application
- Under-fetching – having to request more data because the client didn’t request enough the first time. Retrieving a product’s average rating but then accidentally forgetting to retrieve the first five reviews is an example of under-fetching
- Lack of discoverability – REST isn’t a specification and therefore lacks any form of discoverability or introspection. Clients have no idea which APIs are available
- Inconsistent authorisation and authentication – vendors and internal teams routinely offer different authorisation and authentication schemes, which puts the onus on the client to figure out. Rendering a single page on a website may require a call to APIs from a dozen or more vendors
APIs are unequivocally amazing, but they are built by and for the producers of the APIs – not the clients that consume the APIs.
Enter GraphQL
Enter GraphQL. Facebook had these exact same challenges with APIs, only worse because so many of its users are on bandwidth and performance-constrained mobile devices.
Imagine the number of API calls to build a user’s Facebook timeline. Now, imagine performing all of those queries from an old Apple Watch over a poor Internet connection. Facebook built a specification for how to query for data called GraphQL. The GraphQL Foundation, the now-home of GraphQL, defines GraphQL as ‘a query language for your APIs’.
Facebook has been using it internally since 2012 and publicly released the specification in 2015. Since then, it’s quickly caught on and is now used by Twitter, Microsoft, Amazon, Google and New York Times, among many others.
With GraphQL, you just make a single query, specifying exactly what data you want to retrieve. The GraphQL layer then makes requests to the individual APIs (from the server-side) to fulfil the request. As a developer, you get a single response containing everything you need to render your new product detail page. Think of GraphQL like SQL, where you can retrieve data from multiple database tables using one query.
GraphQL perfectly solves over-fetching, under-fetching, discoverability, and authorisation/authentication and more.
It’s built explicitly for client-side developers to easily retrieve data from APIs.
It’s really emerged as the standard and it is the ‘glue’ for composability.