Set up a custom remote source
Follow this guide to add 3rd party content to your web application using Prepr.
Introduction
When creating content items for your web application, you may want to reference content stored in an external system such as another CMS, legacy system, or eCommerce platform. With Prepr, you can easily use any 3rd party system as a remote content source by following the steps below.
Check out the predefined remote sources doc if you want to integrate to Commercetools, Commerce Layer or Typeform.
Step 1: Set up your custom API endpoint
In this step you need to prepare the API endpoint so that Prepr can make the calls to your external system.
Data format
- Make sure your custom API response conforms to the predefined structure and format as follows:
{
"items": [
{
"id": "unique_reference_id",
"created_on": "2019-11-21T12:51:03+00:00",
"changed_on": "2019-12-21T12:51:03+00:00",
"body": "Title that will be displayed in Prepr",
"description": "Descrtiption text displayed with the title",
"image_url": "https://picsum.photos/200/30",
"external_url": "https://example.com/admin/edit/products/9387498273",
"data": {
"key": "value"
// This key value array will be returned within the Content item response.
}
}
],
"total": 256
}
The response must contain the following fields:
- items — an array containing all attributes that should be available as remote content in Prepr. See the detailed attribute description in the table below.
- total returns — the total number of items available. The total value also depends on the search parameters applied.
Attribute | Type | Description |
---|---|---|
id | string | A unique item identifier for internal use only. The identifier should not be reused upon deleting an item. This field is required. |
body | string | An item title for internal use only. This field is required. |
created_on | int | Date in ISO (UTC Timezone) for internal use only, e.g., 2019-11-21T12:51:03+00:00. |
changed_on | int | Last changed date in ISO (UTC Timezone) for internal use only, e.g., 2019-11-21T12:51:03+00:00. |
description | string | An item description for internal use only. |
image_url | string | An image thumbnail URL for internal use only. |
external_url | string | An optional URL to open a page in a web application from within Prepr. The value is for internal use only. |
data | array | An optional single-dimensional key-value array of data returned by the Prepr API in the content item response. The Source API ID's you choose in the remote source fields should correspond with the key values returned in data. |
- (Optional) Define Headers, specific key-value pairs, to add authentication or filters on the API's end. Check out the remote source setup for more details.
Supported parameters
To learn more about how Prepr interacts with the API endpoint, consider the following:
-
Automatic synchronization. To keep your remote content constantly updated in Prepr, your custom API must support filtering on the last changed items. In this case, Prepr will call the API with a
changed_since
param to refresh your items every 15 minutes. For example,website.com/prepr/feed?changed_since=1583414373
(UTC timestamp). -
Pagination. The API must work with the
skip
andlimit
params to paginate params, and the API response should contain a maximum of 50 items. For example,- Page 1:
website.com/prepr/feed?skip=0&limit=50
- Page 2:
website.com/prepr/feed?skip=50&limit=50
- Page 3:
website.com/prepr/feed?skip=100&limit=50
, etc
- Page 1:
-
Search. To help editors search for a remote content item, Prepr calls the external system URL with the
q
param containing the editor's input, for example,website.com/prepr/feed?q=Looking%20for%20an%20item
. In this case, the total response will be updated with the filtered number of matching items. -
Locale. To help editors search for a remote content item, Prepr calls the external system URL with the
Prepr-Locale
header. This header, which is based on ISO 639-1 standards (e.g.,en-US
), reflects the editor's current viewing language. This feature enables you to customize your feed according to the viewing language. (This is necessary only if your feed supports multiple languages).
Step 2: Add the custom remote source in Prepr
Now that you’ve set up your custom API endpoint, proceed with the configuration in Prepr. You’ll need to connect Prepr to your external system using the API credentials. To add a custom remote source, follow these steps:
- Click the Schema tab to open the Schema Editor.
- On the Schema Editor page, navigate to the Remote content section and click Add source.
- In the opened dialog window, choose to add a custom source.
- In the next screen, name and describe the source as follows, then click Add.
Field | Description | |||
---|---|---|---|---|
Display name | A unique name to identify this source in Prepr. | |||
Type name | A name used for accessing this source through the API. The value is generated automatically and matches the Display name you specified. | |||
Base URL | The endpoint URL that is used to make the API calls. Refer to your external system API specification. | |||
Domain(s) | An external system domain to be allowed in Prepr. It guarantees Prepr will use only domains approved for authorized access to data. | |||
Header | Add the key-value pair to pass additional information about your API request. This key-value array will be returned within the Content item response. | |||
Button | A unique name to identify this source in a content item. | |||
Icon | An icon to identify this source in a content item. |
- Add fields to your remote source in Prepr and map them to the corresponding fields in the external system. Prepr will use those fields to retrieve and store content from your external system.
a. To add fields to the remote source, drag and drop the desired field type from the list on the right into your source. You can choose from the following field types:
b. Then, set the Display name to the Prepr field name and set the Source API ID to the corresponding field name from your external system:
Note
Once you set up the custom remote source in Prepr, an access token will be generated automatically. You can find it under Settings > Access tokens. Prepr will use the token as a credential when making API requests.
Step 3: Add remote content to your content item
Once you’ve connected to the external system and added the Remote content field to your model, you can add the remote content to a content item using the following steps:
- Navigate to the Content tab and click on the desired content item from the list.
- In the remote content section, click the button to add new items (in our example – Add product), search through the catalog and add the desired items to the content item.
- Save and publish this content item to complete the setup.
All done
That’s it. Now your web page includes 3rd party content. Prepr will synchronize your remote content automatically to keep it up to date.
Next steps
Now that you’ve added products from your external system to the content item, you can retrieve the corresponding data using the API. Check out the following docs: