Imagine a scenario of recreating an IMDB website on Contentful. In this setup, every film entry would refer to content types describing a movie genre, cast, production house, and ratings. If a user needs to know how many movies are thrillers, the ideal way to go about it would be to fetch all the films that have genre as 'Thriller'.

Previously, there was no easy way to do it because the Content Delivery API (CDA) did not allow filtering of entries by values of their reference fields.

To address this problem, Contentful has introduced a new filtering capability to the APIs, enabling the user to query for content based on the fields of referenced entries. The following query explains how to get all the thriller movie credits in a single API call:

https://cdn.contentful.com/spaces/my-space-id/entries/
    ?content_type=movies
    &fields.genre.sys.contentType.sys.id=genre
    &fields.genre.fields.label[all]=Thriller

It can be extended one step further, by using multiple values to filter only thriller movies which were made under the banner of Universal Studios.

https://cdn.contentful.com/spaces/my-space-id/entries/
    ?content_type=movies
    &fields.genre.sys.contentType.sys.id=genre
    &fields.genre.fields.label[all]=Thriller
    &fields.productionhouse.sys.contentType.sys.id=productionhouse
    &fields.productionhouse.fields.name[all]=Universal Studios

The reference can also be combined with the select operator to streamline the type of information required in the response.

It is important to understand that search on reference fields only works with entries. It cannot search assets the same way, and the search can only be one level deep. To ensure consistent performance, the number of searchable reference fields is limited to two.

Search on reference field values is supported by all the REST APIs (Content Management, Content Delivery, and Content Preview) and all the SDKs.