ContentSync Logo

Contentful API Compatibility

Contentful provides a very robust and developer-friendly set of APIs that the majority of React and Next.js developers are familiar with. That’s why Content Cloud APIs follow the same standard provided by Contentful. This makes it very easy for developers to start using Content Cloud if they already have experience with Contentful from other projects. This applies to both the REST and GraphQL APIs of the CDN, Live, Preview, and Dev endpoints.

Content Cloud translates and optimizes the content model of upstream sites and services to achieve this. Where frontend developers usually struggle with, e.g., Drupal’s native JSON:API, consuming the content through Contentful-like APIs is much more straightforward. As Content Cloud is technology-agnostic, developers can consume content and data from any upstream service they have connected simply by configuration.

While we have put a lot of effort into maximizing compatibility, there are some smaller changes to consider that we have documented below. If you are unsure about how to implement a certain use case or translate requirements into this API from Contentful, please reach out to us.

Differences

Image API

  • fit: scale and thumb are not supported.

    • You can use scale-down to provide a smaller image, but images won’t be upscaled by the Image API.

    • You can set your own dimensions for creating a thumb version.

  • focus: No support for face / faces parameter.

  • format: The tiff format is not supported.

  • rounded: Rounded corners are not supported.

Content model

Content type definitions are structured differently, as Content Cloud works with more systems than just Contentful, but all content types are interoperable; only the format for defining them is slightly different. You can check out the REST API’s content type endpoint to learn more about the format. The resulting structure for the content itself is identical.

E.g., content type machine names start with an uppercase letter in Content Cloud.

GraphQL endpoint

Different names or nesting

  • .contentfulMetadata is .sys.metadata

Limitations

  • metadata.tags.* only supports contains_some filter.

  • metadata.tags.* only supported in the root Filter object.

  • Filter [contains] currently checks for substrings instead of behaving like a search. Please use the general .search filter to search for text in content.

REST endpoint

Metadata

.contentfulMetadata is .metadata.

Fields

Fields aren’t indexed by locale. The locale is identical for the whole entry and available under sys.locale as locale wildcards are not supported.

Links are resolved as direct descendants of the field rather than included as include.Entry and include.Asset properties. This will change in a later release but doesn’t affect the auto-generated REST client, as the REST client will automatically resolve those links in fields to provide the actual content. If you are already using the auto-generated clients, this won’t affect you.

Limitations

  • Filter [match] currently checks for substrings instead of behaving like a search. Please use the general .query filter to search for text in content.

Fields

Int field

Int fields in Contentful are stored as doubles, which brings their range of allowed values to something between int32 and int64, whereas Content Cloud stores them as native int32 numbers. Instead, Content Cloud provides a native int64 type for large numbers to maximize compatibility with other services and sources like Drupal that offer a bigger range than doubles.

Unsupported Contentful features in Content Cloud

Rich text fields

Rich text fields require a ProseMirror module in Drupal. We are using a custom ProseMirror module that will become open source soon. This module can automatically migrate existing Drupal CKEditor5 HTML and translate it into a proper rich text format that’s more suitable for omnichannel publishing. If you are interested in early access, please reach out to us.

GraphQL API

The following is not supported:

  • preview option per collection.

    • Can only be set for the whole query as we’re using a different API endpoint to simplify access control.

  • Automatic Persisted Queries (APQ)

  • Filter .metadata.tags_exists

  • Query.assetCollection

  • Query.asset

  • Query.entryCollection

REST API

The following is not supported:

  • Relational field filters.

  • metadata.tags.sys.id[all].

Sync API

There’s no Sync API for local replication. You can use filters to query for updated content, but this will not include what content has been unpublished or deleted in the meantime. If you have a use case for this, please reach out to us to explore alternatives.

Additional API features

Content Cloud extends Contentful’s APIs in a couple of ways to improve query performance for upstream content, especially from traditional CMSs like Drupal.

Preview Assets (embargoed content):

If a user has access to preview content and to the preview assets API, the asset URLs are automatically provided to the user instead of requiring a separate request to the asset API with an Asset key.

Embedded types

Some types, like Paragraphs, Bricks, and object properties from Drupal, are embedded and stored as fields rather than separate entities. This improves performance for content that is not shared between multiple types. While these types improve performance and storage, they will show up as simple types. Multi-value fields are arrays rather than collections, meaning you cannot filter or order the values.

Additional options

  • REST

    • ?embed= to include inline documents like nested properties or paragraphs/bricks from Drupal.

  • Content Types

    • Besides regular 32-bit floats and integers, Content Cloud also supports 64-bit doubles and big integers. Big integers are serialized as strings in the interfaces to maximize compatibility.

Some features you can mimic with specific export settings. Custom Tag IDs from Contentful, for example, can be stored in the .customId system property. This would alter queries to require using tags.customId instead of tags.id.