Integration Fields are still in beta and will be progressively deployed to all repositories. This feature allows you to connect your Prismic repository to an external API. If you don't already have Integration Fields in your repository, don't hesitate to reach out on the community forum and send us a message to get it activated.
In this article we'll show you how to create a new Integration Field for a custom API. If you want to know more about Integration Fields in general, you can learn the basics of Integration Fields.
Connect your custom API and allow an editor to easily add information to your pages. Let's go through the steps needed to set this up.
Integration Fields specification for Prismic
Your API will need to return results in a specific format to be compatible with Integration Fields.
API response format
Here is an example of what your API response should look like:
“title”: “Item Title”,
“description” : “Description of the item.”,
“image_url” : “http://...”,
“last_update” : 1509364426938,
// The data to be returned for the item in the prismic API
Top level required fields for the response
At the top level of the response there are two fields that are required.
results_size : The total number of items to index. It is used by the Integration Fields to know how many pages to crawl when syncing the data. Pagination is discussed further down this article. Note that the results_size must be a number.
results : An array of all the items that you want to index for the Integration Field. The results must be sorted by the last_update field, and the array must have a maximum of 50 items per page. Pagination is discussed further down this article.
Required fields for each item in the results
Each item in the results array must have the following fields.
id : The unique ID of the item. It is used to identify products when doing an update for the Integration Field. Note that the result's ID must be a string.
title : The title of the item. It is used as the title in your Integration Field panel for a result. An example of this is provided below.
description : The description of the item. It is used as the description in your Integration Field panel for a result. An example of this is provided below.
image_url : The image url of the item. It is used as the image in your Integration Field panel for a result. An example of this is provided below.
last_update : The timestamp of the last update for this specific item. Make sure that your API results are sorted by this field from newest to oldest.
blob : The JSON object containing the data for this item. This data will be returned by Prismic's API when a content editor selects an item from an Integration Field. Take note that the size of this field will be limited sometime in the future.
As mentioned above, the results array can have a maximum of 50 items. If your API contains more than 50 items, then you will need to set up pagination.
The page number for the API must be passed as a parameter in the url as shown here.
The first page of results will be
?page=1 and so on.
You can add an access token to protect your API. The authentication mechanism is pretty simple. The token will be used as the 'username' for the Basic Auth flow. The password will be left blank.
This is optional.
Meta data for the Integration Field panel
For each result in your API an entry will be created in your Integration Field. Here is an example of what it will look like in the Integration Fields panel in your prismic repository.
The information that appears here is determined by the
image_url fields described above.
Note that this data will not be passed to the prismic API. If you want to have this data available, you will need to duplicate these fields in the
Create your custom integration field
Once your API is ready and compatible with our specification, you just have to create a new Integration Field for a Custom API. Give the Integration Field a name and description, then enter your Endpoint and optional Access Token.
Once you click Save, the Integration Field will automatically begin to crawl your custom API and sync all your items & data. Once everything is synced, you'll be able to add this field to your Custom Types.
Check out the following links to learn more about what comes next.