Integration Fields are still in beta and will be progressively deployed to all repositories. This feature allows you to connect your prismic.io repository to an external API. If you can't see the Integration Fields options in your repository's settings, don't hesitate to ask via the chat support or our Slack community. 

 

Introduction

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.io

Your API will need to return results in a specific format to be compatible with the Integration Fields.

API Response Format

Here is an example of what your API response should look like (note that the result's ID must be a string):

{
  “results_size”: 144,
  “results”: [{
    “id”: “my_item_id”,
    “title”: “Item Title”,
    “description” : “Description of the item.”,
    “image_url” : “http://...”,
    “last_update” : 1509364426938,
    “blob”: {
      // 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.

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.

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 is the data that will be available in the prismic API when an editor selects this item from the Integration Field. Take note that the size of this field will be limited sometime in the future

 

API Pagination

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.

?page=2 

 The first page of results will be ?page=1 and so on.

 

Authentication

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 title, description, and 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 blob data. 

 

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.

 

Synchronization

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.

 

Next Steps

Check out the following links to learn more about what comes next.

Add your Integration Field to a Custom Type
Selecting an Item in the editor

Did this answer your question?