Push API
The Push API is used to push structured data to Springboard to make it searchable. Send data using the Save method to create or update documents. Use the Delete method to remove those documents.
Prerequisites
Before using this API, complete the following prerequisites:
Add the push data source
Create the push data source using the procedure in Add a push data source.
Obtain the Datasource ID
-
In the Applications Manager screen, select the application to modify.
-
In the application’s Hub screen, click the Data Sources icon in the left panel, or scroll to the Data Sources section of the screen and click Manage in the top right corner of the section.
-
In the Data Sources screen, point to the data source to edit and click View/Edit to the right of the entry.
-
Copy the value in the Data source ID field on the Details tab of the Edit Data Source screen.
For information about adding or editing a push data source, see Manage Springboard data sources.
Obtain an access token
Before sending a Push API request, use the Authentication API with the scope value of datasource.push to generate an access token. The access token is used to authenticate your requests.
HTTP request guidelines
The following guidelines apply to the Push API endpoints:
-
The maximum HTTP request body size is 1 MB.
-
If the request cannot be completed within 10 seconds, the server returns a 504 timeout error.
-
Each request must contain 200 or fewer documents.
Basic POST request
The Save method uses a POST operation that creates or updates documents in Springboard. The request requires the externalId, document.title, and type: content fields and values.
| Key | Description |
|---|---|
|
The title of the document. |
|
The unique identifier of the document. The |
|
Identifies the kind of information contained in the document. Specifically, it indicates the data model schema to which the document conforms. The only supported value is |
The following example displays a minimal POST cURL request. Replace DATASOURCE_ID with your data source’s ID. Replace ACCESS_TOKEN with the access token you generated using the Authentication API. Replace the metadata fields and values with any custom metadata fields and values.
curl --request POST 'http://DATASOURCE_ID.datasources.lucidworks.com/push' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '[
{
"type": "content",
"object": {
"externalId": "fd110486-f168-47c0-a419-1518a4840589",
"metadata": {
"KEY1": "VALUE1",
"KEY2": "VALUE2"
}
},
"document": {
"title": "title2",
"description": "desc",
"body": "body",
"author": "author",
"createTimestamp": "2022-10-06T21:35:11Z",
"lastModifiedTimestamp": "2022-10-06T21:35:11Z",
"languageCode": "en-us",
"url": "https://example.com/books/",
"thumbnailImage": "https://example.com/img.jpg"
}
},
{
"type": "content",
"object": {
"externalId": "8084969c-bd23-40f7-9acf-c68d6798bec2",
"metadata": {
"FIELD1": "VALUE1",
"FIELD2": "VALUE2"
}
},
"document": {
"title": "title22",
"description": "desc",
"body": "body",
"author": "author",
"createTimestamp": "2022-10-06T21:35:11Z",
"lastModifiedTimestamp": "2022-10-06T21:35:11Z",
"languageCode": "en-us",
"url": "https://example.com/home/",
"thumbnailImage": "https://example.com/img2.jpg"
}
}
]'If no errors are detected in the batch, a 202 Accepted message displays. The batch of documents posted to your Springboard application can be searched in Experience Optimizer. For more information, see Push data source results in Experience Optimizer.
| To view the list of responses and error messages, click View API specification and scroll to the response section. |
Basic DELETE request
The Delete method uses a DELETE operation that removes a batch of documents from Springboard. The request requires the externalId and type: delete fields and values.
| Key | Description |
|---|---|
|
The unique identifier of the document to delete. The |
|
Identifies the operation being performed. Currently, the only supported value is |
The following example displays a minimal DELETE cURL request. Replace DATASOURCE_ID with your data source’s ID. Replace ACCESS_TOKEN with the access token you generated using the Authentication API.
curl --request DELETE 'http://DATASOURCE_ID.datasources.lucidworks.com/push' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '[
{
"type": "delete",
"externalId": "fd110486-f168-47c0-a419-1518a4840589"
},
{
"type": "delete",
"externalId": "8084969c-bd23-40f7-9acf-c68d6798bec2"
}
]'If no errors are detected in the batch, a 202 Accepted message displays. The batch of documents deleted from your push data source can no longer be searched in Experience Optimizer or your website’s search application.
| To view the list of responses and error messages, click View API specification and scroll to the response section. |
Processing information
Springboard validates the entire batch of documents before processing them. Save requests and delete requests handle errors differently.
Save requests
If there are no errors in any of the documents in the batch, Springboard processes the batch.
The Save method creates and updates documents in the same operation. If an individual document contains an externalId that does not currently exist in the data source, Springboard creates a new document. If an individual document contains an externalId that currently exists in the data source, Springboard updates the existing document.
If there are errors in any of the documents in the batch, the entire batch fails, and none of the batch is processed. The errors are logged and you must correct them before you resubmit the batch for processing.
New and modified entries may not be reflected immediately in search results.
Delete requests
If there are no errors in any of the documents in the batch, Springboard processes the batch. If an individual document contains an externalId that currently exists in the data source, Springboard removes the document. If no document with the specified externalId exists, Springboard ignores that externalId and the Push API does not generate an error.
If there are errors in any of the documents in the batch, the entire batch fails, and none of the batch is processed. The errors are logged and you must correct them before you resubmit the batch for processing.
Deleted entries may not be reflected immediately in search results.