Connect external data

Work with external data sources

A core task for composable systems is bringing content and data together from various sources.

Data integration and aggregation involves:

  • Configuring connection details for APIs or headless systems, such as API endpoints and access settings and credentials (for example, project IDs, API keys)
  • Performing API calls to query the desired content or data
  • Mapping the returned data payload to frontend components for rendering

If you don't use a digital experience composition platform (DXCP) like Uniform, these tasks require developers to create a lot of custom integration and orchestration code. Experiences become hard and expensive to write, make performant, and to maintain. This "glue code" is a major source of defects and downtime.

Integrations are often hard coded into the application business logic, limiting the ability for marketers to build digital experiences without being dependent on the help of developers.

Uniform gives developers a streamlined way of integrating external data and content into the experience layer. By leveraging modern, front-end frameworks and deploying to performant, scalable hosting environments, developers can empower non-technical authors with little or no glue code.

Canvas offers two approaches on how to connect to external data:

  1. Edge-side data aggregation using Edgehancers and data connections
  2. Application-level data aggregation using custom parameters and enhancers


Using Edgehancers is the recommended approach for connecting to external data sources. This method is easier to implement and is more performant.

If you need more control over how data is fetched, it's also possible to use both approaches within the same project.

Data fetchingOn CDN edge through the Uniform Edge APIFront-end application or custom hosted API proxy
Supported rendering modessupports both dynamic (SSR, ESR) and static (SSG, ISR) modesstatic mode (SSG, ISR) is recommended, dynamic mode supported with custom optimization
Caching supportYes, with granular cache invalidation controlsRequires custom code
No-code integrationsYes, fully configuration basedNo, enhancers need to be added per integration in code
Coupling of external data source with UI componentsNone, Canvas and UI components are decoupled from data sourcesSome, integration specific parameters are part of the component
API secrets managementSecurely stored and managed by Uniform for performing API calls on the edge. Front end usually doesn't need any API secrets.Front end application needs to manage secrets for each integration with environment variables for data fetching

Edgehancers are the server-side, no-code equivalent of enhancers that enhance compositions with data from external data sources. In contrast to enhancers, the data fetching and caching of the enhanced composition data happens on the CDN edge, hence the term Edgehancers.

To be able to fetch external data on the CDN edge you need to provide the connection and query details by configuring your data sources and data types.

Data connections are the mappings between a property of an API response and the value of a parameter of a component in Canvas. These connections to your UI components are made in the Canvas editor and don't require any code changes.

Enhancers are functions executed in your front-end application. Their purpose is to fetch external data and optionally transform the results which are then passed into the UI components for rendering.

Enhancers are the programmatic way of connecting to external data in Uniform. While the use of Edgehancers and data connections is recommended whenever possible, there might be situations where enhancers are a better solution. Examples include:

  • you need to change the API request at runtime through custom code
  • an integration doesn't yet support Edgehancers for data fetching

Learn more details in the enhancer guide.

The data returned by Edgehancers can be further transformed by enhancers. This is useful for text formatting or custom rendering instructions (like rich text or responsive images).


The following sections are only relevant if you are using an Edgehancer-based approach to connect to external data sources.

To connect your components to external data, first you need to specify where the data is coming from and how to connect to it.

On a high-level this involves following steps in Canvas:

  1. Define data sources, which represent a data instance such as a CMS instance or API base URL, and store secure credentials.
  2. Define data types, which are a specific type of data contained in a data source such as a CMS content type or REST API resource.
  3. Create a data resource to make a specific instance of a data type available to composition or pattern, such as a specific piece of CMS content or a product query result.
Connecting external sources to Uniform design system components requires you to use data types.

Here is a visualization of these steps using an example "Search" data type:

A data source defines the common settings needed to integrate with an instance of an API. Data sources are links to sets of data. Examples of data sources might include:

  • The development instance of your CMS using a specific API key
  • A publicly-available API such as, using an authorization header (resources in this API are data types)
  • Any composable system that offers an API is a candidate to connect to Uniform


Access credentials for APIs should only be configured in data sources where they're secure.

These credentials aren't exposed through any public API, SDK or CLI commands. They're only used internally by Uniform's Edge API to perform API calls to external services.

Data sources are based on data connectors that can provide bespoke and service-specific user interfaces and settings for managing data sources, data types, and data resources.

By default Uniform provides two built-in data connectors:

  • JSON data is a way to provide arbitrary, static JSON data for prototyping or mocking APIs. Adding this data source will let you create data types for individual JSON document data sources. You will enter:
    • Name: Identifies the data source
    • Public ID: Uniform auto populates this field with the information you added in the "Name" field. You can change the information in this field, but only until the data source is saved. Once created, you can't change it.
  • HTTP requests bring in data from any publicly available API, such as REST or GraphQL APIs. These are a great way to add external APIs just by configuring some endpoints without having to create a custom integration. You will enter:
    • Base URL of the API
    • Query parameters
    • Headers

In addition, installed integrations can also add their own data connectors to a project. Integrations provide a simplified user experience for retrieving data from their target system. You can also build your own integrations.

Once data sources are set up, you can start defining which kinds of data you want to connect to by creating a data type. Data types represent a specific form of data that you want to retrieve from a data source, such as a specific product or the results of querying for a content type or product category. Behind the scenes, they extend the base URL from the data source with a specific resource path for the data type.


Any query strings or HTTP headers defined for the data source are automatically applied to its data types. If both define the same key, the data type will overwrite the data source.

  1. Log into your project in Uniform and select Data types from the Canvas menu.
  2. Click the "Add data type" button. A dropdown list of available data sources is provided. The list will include any integrations that are in the project and support Edgehancers, and the built-in HTTP request or JSON data sources. If the project doesn't have any configured data sources yet, this is can be done by choosing the "Create new" option in the appropriate section.
  3. Depending on the chosen option the interface in the next step will differ:
    • JSON data: allows you to enter a static JSON string into the "JSON Data" input
    • HTTP request: define the specifics of the API call definition
      • Relative path of the API endpoint
      • Variables for dynamic queries
      • Query parameters
      • Headers


      If you have worked with API tools like Postman or Insomnia this kind of configuration should feel familiar

    • Integration: shows integration-specific inputs for configuring which external resources to fetch from the external system
  4. Give the data type a name and public ID
    • Name: Identifies the data type
    • Public ID: Uniform auto populates this field with the information you added in the "Name" field. You can change the information in this field, but only until the data type is saved. Once created, you can't change it.
  5. Optionally review the Advanced Options
    • Allowed on Components: Whitelist of components on which the data type can be used. Defaults to all components if left empty.
    • Enable Edge Cache: turn this off to disable caching of external data on the edge. Enabled by default.
    • Edge Cache Time: How long (in seconds) the resource data should be cached at the edge before being updated. Default is 30 seconds.
    • Edge Cache Purging: Provides purge keys to invalidate the edge cache for this data type
  6. Click Save to save and return to the Data types overview screen or click Test to check if the correct data is returned by the API call
    Example of testing the API response of a data type

You can create custom variables for HTTP Request data types so authors can provide an input value for any data resource of that data type.

These variables can be inserted in any part of the API query which includes API path, query parameters and headers. To insert a variable you need to type ${variableName} in the input field. Or you can click on the Insert Variable button on the input field and select the desired variable from the list in the dropdown:

Example of inserting a custom variable in the path of an API endpoint.

To create a new variable click on the add variable button and fill out the name, help text and default value in "Add Variable" form. Once you click Ok the variable is added to the variable list and can be inserted in the desired location (see screenshot above).

Example of adding a custom variable to a data type.

Once a variable is defined it will show up as a text input on data resources that are instantiated from the data type.

Example custom variable on a data resource.

To use external data on your composition or pattern you create a data resource to make a specific instance of a data type. The data resource will contain the JSON response that's returned from the API call using the user-provided inputs or selection. Often, the data resource represents a specific entity from an external system, such as a piece of CMS content or the result of a query such as a list of products from a PIM that matches certain search criteria.

The individual elements of data from the data resource can then be connected to component parameters in the Canvas editor. For example a data resource contains the data of an blog post and it should be displayed in a generic Hero component. In this case you connect the properties of the article, which Uniform calls data elements, to the parameters of the Hero component:

  • Blog post title -> Hero title

  • Blog post image -> Hero image

  • Blog post slug -> Hero link

    Example connecting a blog post to a hero component.

These steps assume that the author is going to fetch information at the component level, and that data resources haven't be pre-configured through the use of patterns.

  1. Start by creating or editing a composition from Content > Compositions in Uniform. As you add components to your composition, you'll see the available parameters in the property panel.

  2. Add a component to your composition. Click the ••• to expose the option to "Connect to external data" This selection opens additional configuration options to add a data resource to the composition.

    Data resources can also be managed from the ••• next to the "Save" and "Publish" buttons. Managing data resources includes options to:

    • View source
    • Delete
    • Check the status of pattern data resources or loop data resources.
  3. Select a data type from those available in your project. Each data type may have additional configuration options, such as filtering results.

    You can now select what information to bring into specific fields in your component. For example, if you have selected an "Blog post" from a CMS as your data resource, you can now browse to a specific blog post title for entry in a hero component.

    Example of selecting a piece of information from an integration for a composition.
  4. Choose a parameter to populate, click the ••• above the field, and select "Connect to external data." You will see the available information, usually in a nested display for complex items with many attributes. Select the information you'd like to have brought into the composition and click "Connect."

    About this step

    You can also search for the desired element or add new data resources from this interface.

    The data from your system of record is now connected to your composition. You can also edit the data connection (to change to link a different piece of data) or disconnect the data connection. Disconnecting the data will leave the content in the field so you can either edit or delete it.

    Repeat this step with other component parameters that should be connected to the data resource


The above steps show the basic way of connecting external data to compositions with data resources which enables getting quick results and using data in components in a flexible way.

The downside is that the data connections must be re-created for each component instance. Also it can be challenging for non-technical users to create the connections between data resources and component parameters as they might not be familiar with the JSON data structures of the external systems.

For a simplified editing experience the recommended approach is to use patterns with pre-connected data