Custom integration
Follow this guide to add 3rd party content to your web application using Prepr.
Introduction
When creating publications 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.
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.
- 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. Keys will be returned using the StudlyCaps formatting. |
- (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.
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: {{url}}?skip=0&limit=50
Page 2: {{url}}?skip=50&limit=50
Page 3: {{url}}?skip=100&limit=50, etc.
- Search. To help editors search for a remote content item, Prepr calls the external system URL with the
q
param containing the editors' 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.
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. Learn more on how to add a custom remote source.
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.
Step 4: Retrieve remote content using the API
Now that you’ve added products from your external system to the content item, you can retrieve the corresponding data using the API. Please refer to the example code snippets below:
{
Pages {
items {
content_integrations {
key1
key2
}
}
}
}
curl --location --request POST 'https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{ Pages { items { content_integrations { key1 key2 } } } }","variables":{}}'
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
const graphql = JSON.stringify({
query: "{ Pages { items { content_integrations { key1 key2 } } } }",
variables: {}
})
const requestOptions = {
method: 'POST',
headers: myHeaders,
body: graphql,
redirect: 'follow'
};
fetch("https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
// WARNING: For POST requests, body is set to null by browsers.
const data = JSON.stringify({
query: "{ Pages { items { content_integrations { key1 key2 } } } }",
variables: {}
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);
<?php
$client = new Client();
$headers = [
'Content-Type' => 'application/json'
];
$body = '{"query":"{ Pages { items { content_integrations { key1 key2 } } } }","variables":{}}';
$request = new Request('POST', 'https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
{
"data": {
"Pages": {
"items": [
{
"content_integrations": [
{
"key1": "Value 01",
"key2": "Value 02"
},
{
"key1": "Value 11",
"key2": "Value 12"
}
]
}
]
}
}
}
That’s it. Now your web page includes 3rd party content. Prepr will synchronize your remote content automatically to keep it up to date.