New GraphQL API features: One call to rule them all

We've boosted the performance of our GraphQL API with three new features (announced as part of our bigger launch event on Oct. 4). These features are nested filtering, automatic persisted queries, and increased complexity limits. 

Taken together, they further extend the advantages that GraphQL can bring to those who use Contentful, ensuring that the content they deliver to their customers is expedited as efficiently and robustly as possible. 

In this post, we’ll walk through each new GraphQL feature one by one. We’ve also made a video to give a quick overview:

GraphQL results in snappier software (and happier customers)

GraphQL brings numerous advantages to developers who are used to working on enterprise applications that require large amounts of data cross-referenced over potentially multiple backend systems. 

GraphQL enhances efficiency by reducing over-fetching of data, allows for versionless APIs, and creates a single point of truth by collating data from multiple resources into one HTTP call. 

Plus, the system’s strong typing ensures data consistency and its introspective nature aids in self-documentation.

The flexibility provided by GraphQL empowers frontend developers to create more performant applications, reducing data fetching and making more precise data fetches which leads to snappier software and happier customers.

And now we've made it even better with a trio of new features.

New feature: Nested filtering

Nested filtering applies to queries in which a developer is looking to filter specific data that is nested within another data type.

In Contentful terms, this may be a content type that has a reference to another content type. Let’s start with a simplified example and then look at a more advanced one.

Let’s suppose we have an ecommerce website that sells books and we want to get all authors and their books. Our query might look something like this:

This query works well if we want to get all authors and their books. But there might be tens of thousands of authors and thus potentially hundreds of thousands of books!

We don’t want our clients to download all this data just so we can sort through it. Instead, we can refine our query using a filter like so:

Here we are filtering only authors whose name is “Aaron.” If we are building out our store pages alphabetically, this helps minimize the amount of data we need to send over the wire and download to our clients by telling GraphQL to only give us the authors we are specifically looking for. 

But what if we want to go deeper and only find books by Aaron(s) whose genre is fiction? In comes nested filtering. With nested filtering, we can repeat this process again, in the nested content type of books:

Again, we are saved the trouble of having to download all the books written by all Aarons just to filter client-side which books are fiction vs. non-fiction. In our nested filter, we can ask the GraphQL API to directly give us a) all books by Aaron and b) only fictional books by Aaron.

To sum up, nested filtering fetches exactly the data your application needs for improved performance and simpler frontend development by allowing queries that have filters within filters.

New Feature: Automatic persisted queries

Spinning off nested filtering, we have another update which is automatic persisted queries. In the past, there was an 8kb limit to request sizes which would cause developers to have to find workarounds, hacks, or rethink how they managed their data. 

Now, with automatic persisted queries, requests can go above the 8kb limit. By adopting this specification, designed by Apollo, users can send us just a hash of their query (which we store along with the original query).

This allows a user to send smaller queries: you only need to send the hash of the query and any variables that form the query, thus reducing the size of the request, and allowing us to cache it at our CDN.

This is useful for when your data structures are highly complex. Used in tandem with nested filtering, this feature could open the doors for many advanced users who are looking to craft highly specific and complex queries for their software solutions.

New feature: Increased complexity limits

In the past, Contentful only allowed for GraphQL requests with up to 11,000 entities per request. Now, with increased complexity limits, users can reach out to Contentful to have this 11,000 limit increased. 

To understand how complexity is calculated, let’s take a look at the following example:

The above example has a maximum complexity of 20 because only up to 20 authors will be returned. Let’s look at a bigger query:

The above query can have a maximum complexity of 220. This is calculated by taking a total of 20 authors and 200 books (10 books per author), equalling a total of 220 entities (20 authors + 200 books).

While the baseline complexity limit of 11,000 may seem like a lot, there are many use cases where tens of thousands of entities may need to be resolved at a time in order to build a frontend experience.

Out of the box, all users will get the limit of 11,000 entities, but with a request to Contentful, that limit can be increased at no extra cost.

GraphQL is the foundation of our broader strategy

All of these powerful enhancements to our GraphQL API underpin the broader set of features we announced at our big launch event on Oct. 4. The explosive growth of companies’ digital ecosystems requires more powerful tools to manage and deliver them.

This is especially true of all our new multi-experience orchestration features, which allow developers to deliver content from multiple Contentful spaces — or even external systems — with a single API call. This creates the potential for more complex content graphs, which are handily supported by the GraphQL API updates above. 

For example, our new orchestration updates include:

• Custom external references, which allow you to deliver content from other systems outside of Contentful (e.g., PIM, ecommerce, DAM) through our GraphQL API. We are starting with select apps in our marketplace (Commercetools, Cloudinary, and Shopify). You can learn more here. 

• Early Access Program (EAP) to build your own custom external references, using serverless Lambda Functions hosted right in your content delivery pipeline (we are calling these Delivery Functions). This will let you unify third-party content from any number of systems. 

• Enhancements to cross-space references, which let developers pull in content from other teams in Contentful (e.g., a product catalog managed in a separate space). For example, these references now work across any environment for better integration with your software delivery pipeline. Unifying these spaces is still done via our REST API, but we are scoping adding it to our GraphQL API as well. 

We also released tools to help digital teams visualize the more complex content graphs they are creating. We made a series of enhancements to our recently released Visual Modeler, to make it even easier for teams to visually collaborate on content models right in Contentful. This tool also nicely shows cross-space and custom external references.

We also made it a lot easier to get started, to reduce the “blank page” problem with new content types, with our recently announced AI Content Type Generator. 

Wrapping up

We're excited to provide a portfolio of new features to help teams create, manage, and deliver the sophisticated content architectures that form the foundation of a modern digital footprint.

Whether they're using GraphQL API enhancements that deliver content more efficiently, orchestration features to unify content, or features which visualize content models, we’re looking forward to seeing what our customers bring to market next.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.