Skip to main content

Contentful Data Source

Contentful is a headless content management system (CMS) that stores structured content and serves it through APIs across spaces and environments. Follow the instructions below to create a new data flow that ingests data from a Contentful source in Nexla.
contentful_api.png

Contentful

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Contentful connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Contentful instance, and click Next; or, create a new Contentful credential for use in this flow.

  3. In Nexla, Contentful data sources can be created using pre-built endpoint templates, which expedite source setup for common Contentful endpoints. Each template is designed specifically for the corresponding Contentful endpoint, making source configuration easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Contentful sources can also be configured manually, allowing you to ingest data from Contentful endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Contentful endpoints. Each template is designed specifically for the corresponding Contentful endpoint, making data source setup easy and efficient.

The source templates call different Contentful APIs depending on the type of content being read. Endpoints that read management-level resources (environments, content types, entries, assets, and locales) call the Content Management API (CMA). The "Search Entries (CDA)" template calls the read-only Content Delivery API (CDA), which serves published content. The "Preview Entries (CPA)" and "Get Space" templates call the Content Preview API (CPA). Ensure that the access token in your selected credential has access to the API(s) used by the endpoint(s) you configure.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    List Environments

    This endpoint retrieves all environments within the Contentful space configured in your credential. Environments are isolated content workspaces (similar to branches) that let teams develop and test content changes without affecting production.

    • No additional configuration is required beyond selecting this endpoint template. The space is determined by the Space ID in your credential.
    • This endpoint is paginated. Nexla automatically pages through results using Contentful's skip and limit parameters, retrieving up to 100 records per page until all environments are fetched.

    Use this endpoint to discover the environment IDs available in your space before configuring environment-scoped endpoints such as List Content Types or List Entries.

    Get Environment

    This endpoint retrieves the metadata and configuration for a single environment by its ID. Use it when you need details about one specific environment rather than the full list.

    • Enter the identifier of the environment to retrieve in the Environment ID field. This field is required. Environment IDs can be obtained from the List Environments endpoint.

    List Content Types

    This endpoint retrieves all content types defined in the space and environment configured in your credential. A content type defines the structure of your content—the fields that entries of that type contain.

    • No additional configuration is required beyond selecting this endpoint template. The space and environment are determined by your credential's Space ID and Environment ID.
    • This endpoint is paginated. Nexla automatically pages through results using skip and limit, retrieving up to 100 content types per page.

    Content type IDs returned by this endpoint can be used to filter entries in the List Entries, Search Entries (CDA), and Preview Entries (CPA) endpoints.

    Get Content Type

    This endpoint retrieves a single content type by its ID, including its complete field definitions. Use it when you need the schema for one specific content type.

    • Enter the identifier of the content type to retrieve in the Content Type ID field. This field is required. Content type IDs can be obtained from the List Content Types endpoint.

    List Entries

    This endpoint retrieves entries from the space and environment configured in your credential using the Content Management API. Entries are individual content records that conform to a content type. Use this endpoint to ingest your full content set, optionally filtered to a single content type.

    • Optionally, enter a content type ID in the Content Type Filter field to retrieve only entries of that type. Leave this field empty to retrieve entries of all content types.
    • This endpoint is paginated. Nexla automatically pages through results using skip and limit, retrieving up to 100 entries per page.

    The Content Management API returns all entries regardless of publish state, including drafts and changed entries. To retrieve only published content, use the List Published Entries or Search Entries (CDA) endpoint instead.

    Get Entry

    This endpoint retrieves a single entry by its ID. Use it when you need to ingest one specific content record rather than a collection.

    • Enter the identifier of the entry to retrieve in the Entry ID field. This field is required. Entry IDs can be obtained from the List Entries endpoint or from the Contentful web app URL when viewing an entry.

    List Published Entries

    This endpoint retrieves the published versions of all entries in the space and environment using the Content Management API's public entries collection. Use it when you want only content that is currently live, without drafts or unpublished changes.

    • No additional configuration is required beyond selecting this endpoint template. The space and environment are determined by your credential.
    • This endpoint is paginated. Nexla automatically pages through results using skip and limit, retrieving up to 100 entries per page.

    List Assets

    This endpoint retrieves all assets in the space and environment configured in your credential. Assets are files managed in Contentful, such as images, videos, audio files, and documents, along with their metadata.

    • No additional configuration is required beyond selecting this endpoint template. The space and environment are determined by your credential.
    • This endpoint is paginated. Nexla automatically pages through results using skip and limit, retrieving up to 100 assets per page.

    Get Asset

    This endpoint retrieves a single asset by its ID, including its file metadata and URLs. Use it when you need details for one specific file.

    • Enter the identifier of the asset to retrieve in the Asset ID field. This field is required. Asset IDs can be obtained from the List Assets endpoint.

    List Locales

    This endpoint retrieves all locales configured in the space and environment. Locales define the languages and regional variants that your content can be localized into (for example, en-US or de-DE).

    • No additional configuration is required beyond selecting this endpoint template. The space and environment are determined by your credential.
    • This endpoint is paginated. Nexla automatically pages through results using skip and limit, retrieving up to 100 locales per page.

    Use the locale codes returned by this endpoint to understand the localized field values present in entries and assets retrieved by the other endpoints.

    Get Space

    This endpoint retrieves the metadata and configuration for the space configured in your credential, such as the space name and default locale. It calls the Content Preview API (CPA), so the access token in your credential must have preview access.

    • No additional configuration is required beyond selecting this endpoint template. The space is determined by your credential's Space ID.

    Search Entries (CDA)

    This endpoint searches published entries using the Content Delivery API (CDA), which is optimized for fast, production-grade delivery of live content. Use it when you want to ingest a targeted subset of published content based on content type and search criteria. The access token in your credential must have delivery access.

    • Optionally, enter a content type ID in the Content Type field to restrict the search to a single content type. Leave this field empty to search across all content types.

    • Optionally, enter additional Contentful search parameters in the Query String field. These are appended to the request as URL query parameters and let you filter, order, and full-text search your content. Examples include:

      • Field filter: fields.title[match]=launch to match entries whose title contains "launch".
      • Ordering: order=sys.createdAt to sort results by creation date.
      • Full-text search: query=marketing to search across all fields.

    Multiple search parameters can be combined with & in the Query String field. This endpoint is paginated; Nexla automatically pages through results using skip and limit, retrieving up to 100 entries per page. The CDA returns a maximum of 1,000 entries per result set.

    Preview Entries (CPA)

    This endpoint retrieves entries using the Content Preview API (CPA), which returns both published and draft content. Use it to ingest in-progress content for staging or review workflows. The access token in your credential must have preview access.

    • Optionally, enter a content type ID in the Content Type Filter field to retrieve only entries of that type. Leave this field empty to retrieve entries of all content types.
    • This endpoint is paginated. Nexla automatically pages through results using skip and limit, retrieving up to 100 entries per page.

    Because the CPA returns unpublished drafts, use it for preview and staging scenarios rather than production delivery. For live content only, use the Search Entries (CDA) or List Published Entries endpoint.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Contentful data sources can be manually configured to ingest data from any valid Contentful API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations, such as targeting a specific environment, applying advanced Content Delivery API query parameters, or calling resources like tags or webhooks.

With manual configuration, you can also create more complex Contentful sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom request parameters.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Contentful API from the Method pulldown menu. Read operations against Contentful use:

    • GET: For retrieving content types, entries, assets, environments, locales, and spaces.

API Endpoint URL​

  1. Enter the URL of the Contentful API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters. The base URL depends on which Contentful API you are calling:

    • Content Management API (CMA): https://api.contentful.com
    • Content Delivery API (CDA): https://cdn.contentful.com
    • Content Preview API (CPA): https://preview.contentful.com

    For example, to list entries via the CDA, the URL would follow the pattern https://cdn.contentful.com/spaces/{'{space_id}'}/environments/{'{environment_id}'}/entries, where {'{space_id}'} and {'{environment_id}'} are replaced with your space and environment identifiers.

Ensure the API endpoint URL is correct and accessible with your current credentials. The access token in your credential must match the API in the URL—a delivery token cannot call the CMA, and a management token cannot call the CDA. You can test the endpoint using the Test button after configuring the URL.

Path to Data​

Optional

If only a subset of the data returned by the API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. This is particularly useful because Contentful collection responses wrap the records in an items array alongside metadata such as total, skip, and limit.

For example, when listing entries or assets, Contentful returns an object with an items array containing the records. By entering the path to this array, you can configure Nexla to treat each element of the array as a record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For Contentful collection responses (such as entries, assets, content types, and locales), enter $.items[*] to treat each element of the returned items array as a record.

    • For single-resource responses (such as Get Entry, Get Asset, or Get Space), enter $ to treat the entire response object as one record.

    Path to Data Example:

    A Contentful entries response contains a top-level array named items. To treat each entry as a record, the path to data would be entered as $.items[*].

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, a Contentful collection response includes a total count alongside the items array. After specifying $.items[*] as the path to data, you can specify a path to the total value to include it with each record in the generated Nexset(s).

Metadata paths are particularly useful for preserving API response context like the total record count or pagination details that apply to all records in the response.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers are often required for API versioning, content type specifications, or custom authentication requirements.

    You do not need to include any headers already present in the credentials. The Authorization header carrying your Contentful access token is added automatically by Nexla based on your credential configuration.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Contentful data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.