Evolving Content Delivery at USA TODAY NETWORK

Co-authored by Tim Kuhlman and Ryan Grothouse

Content published by our newsrooms needs to be immediately available for readers of USA TODAY and our local publications. Our presentation layer has historically made this data available to front end applications through a REST API. With our most recent iteration, we’ve started serving data using GraphQL.

Among the many advantages GraphQL brings to our infrastructure are: the ability to easily evolve our data formats, simplicity for front end developers and a new mental model for our data lifecycle.

Evolvability

With GraphQL queries you specify exactly what fields in a schema you want in the response. For example, in this query I asked for the title and createDate and received in the response those exact fields:

This key characteristic leads to a number of advantages for our data evolvability. With only specified fields in the output, new fields can be added to the data schema without worrying about backwards compatibility and negatively affecting existing consumers of the data. This enables quick incremental changes to the data schema.

Although adding fields is useful, more important for much of our data is the ability to safely remove fields. Reporting on the fields included in each GraphQL query allows full data-driven evolution of the schema — unused fields can be removed quickly and without impacting customers. Reports show which fields are used and also which customer requests a specific field, so if needed, we can work with specific customers. This reporting speeds up the process of data cleanup and reduces coordination friction across the organization.

Simplicity

GraphQL is a simpler solution for front end developers for a few reasons:

• It enabled the collapsing of a number of REST endpoints and API calls into a single service.
• The ability to customize the exact fields your application needs in the returned data can streamline client code.
• Developers can also combine multiple queries in a single request to minimize round trips. The reduced data in responses and the ability to put multiple queries in a single request provides a performance boost.
• GraphiQL offers a great developer experience that is much better than reading out-of-date schema documentation and attempting to piece together queries by hand. With GraphiQL we can easily build and test queries, share queries with colleagues by URL, restore queries from history and explore the available schema. For example, this screen shot shows the autocompletion dialog while writing a query, as well as the built-in schema browser.

Data Lifecycle

RESTful designs forced us to design data models around API resources — whether a singleton or a collection. Real world data models are often far more complex. This has led to API endpoints built specifically for abstracting and aggregating the fetching of several resources.

A simple example is an article with associated images. In a REST framework, we had an endpoint /v1/article/<ID> to retrieve an article. That article has images associated with it. To avoid another 50 calls to get each image from its own endpoint, the image metadata is included in the response. This implies that images are part of an article and not stand-alone assets which can appear in galleries, other articles, etc.

With our RESTful design, clients were disconnected from the “real” data model. With GraphQL, the relation is explicitly expressed in the schema and clients choose how they want the data returned. For some, abstraction from the data model may be desirable. For us, it meant that API clients were speaking a different language than what our content producers and the rest of the organization was speaking. After all, our data model is primarily driven by the “real” workflow of our newsrooms.

In conclusion, API design with GraphQL more accurately represents the complex relationships of our data. This better representation of our data in turn drives business discussions about our data and often leads to new discoveries around inefficiencies and opportunities for improvement, both technical and non-technical. The striking benefit is that the technical implementation is more closely aligned with the business representation of the data. Our content producers, content API team and API clients are now speaking a common language about our data.