But before we dive into the what and how of incoming links, we have a story for you about why we decided to build this feature.
How different content structures affect content management
When they were first introduced, traditional CMSs were appealing because their hierarchical approach to content makes it simple to navigate entries. Every single page falls under a particular category, which in turn could fall under a particular section, and so on. There are certain shortcomings to this structure, sure.
For example, updating individual pages has to be done one-by-one and takes a long time. But the navigation aspect is always straightforward, which is why some legacy CMSs are popular among editorial teams.
The new generation of content management takes a different approach to organizing your entries by eschewing hierarchy and keeping the content flat. This means that pages are organized as transient containers that have a body field for key content, but also have other elements—think author bio, category description, relevant entries, and footer. These other elements are attached to the page like entries, rather than being baked into the page itself. The apparent benefit of this approach is that keeping content up-to-date requires minimal effort. Take updating an author bio, for instance. With flat content structures, if you have to update an author bio across 100 articles, you don’t need to update 100 articles—you only need to update the one entry (author bio) attached to these articles.
However, flexibility can lead to complexity. Because while it’s simple to update the author bio, it’s not always easy to visualize all of the places that link to an entry with an author bio. This has to do with the way databases work, so we won’t dive into that right now. But you can imagine that if you are managing hundreds of entries and at some point decide to delete an entry or amend it, it can have undesired effects. This was the issue brought up by our customers, so that’s why we set out to fix it.
Enhancing your Contentful experience with incoming links
Incoming links are a new set of API search parameters which filter entries that have a field linking to a given entry (
links_to_entry) or asset (
links_to_asset). Available under the
/entries endpoint, these search parameters ease the process of navigating the content graph from children up to their parents in a single API call.
Many use cases benefit from this release, including:
- Simplifying the process of rebuilding only parts of a statically generated website or search index, like in the scenario mentioned above
- Navigating to all possible parent entries linking to a given child entry
- Anticipating the impact of a 'Delete', 'Archive', and 'Unpublish' action on a child entry
- Visualizing and removing circular references in a content model
- Tracking obsolete entries which are not linked to anything and could be removed
Not just for developers: Inbound references UI extension
APIs may be primarily used by developers, but that doesn’t mean that editors can’t benefit from this innovation. In fact, many of our customers chose to implement the lookup of incoming links as their first UI extension. So we created an example UI extension that shows inbound references to an entry in the sidebar of the web app. To get it working, you need to follow all of the usual steps for activating a UI extension.
Getting started with incoming links
To help you get started with incoming links, we’ve updated our reference documentation. In addition, you can find the source code for the example UI extension on GitHub—and yes, pull requests are welcome!