docs

API Documentation

This document provides an overview of the endpoints and functionality offered by the Display’s REST API to interact with databases. The API consists of several routes related to database operations, including importing and exporting collections, tags, and CRUD operations for collection items and tags.

Base URL

The base URL for accessing the API endpoints is https://display.spotside.com/i/<instance-id>/api/v2/.

Authorization

To access the API endpoints, you need to include an API key as a bearer token in the request headers. Generate an API key in the backoffice and include it in the request headers as follows:

Authorization: Bearer <API_KEY>

Replace <API_KEY> with the generated API key.

Import Collection

Endpoint: POST /databases/import-collection

This endpoint allows you to import a collection into a specified database.

Request Parameters

• req.body.code: The code representing the database.
• req.body.data: The data to be imported.

Response

• If the import is successful, the API responds with a JSON object containing the imported documents.
• If the code or data is missing in the request, the API responds with a status code of 500 and an error message in JSON format.

Import Collection (Raw)

Endpoint: POST /databases/import-collection-raw

This endpoint allows you to import a collection in raw format into a specified database.

Request Parameters

• req.body.code: The code representing the database.
• req.body.data: The raw data to be imported.

Response

• If the import is successful, the API responds with a JSON object containing the imported documents.
• If the code or data is missing in the request, the API responds with a status code of 500 and an error message in JSON format.

Export Collection

Endpoint: POST /databases/export-collection

This endpoint allows you to export a collection from a specified database.

Request Parameters

• req.body.code: The code representing the database.

Response

• If the export is successful, the API responds with a JSON object containing the exported documents.
• If the code is missing in the request or the specified database doesn’t exist, the API responds with a status code of 500 and an error message in JSON format.

Import Tags

Endpoint: POST /databases/import-tags

This endpoint allows you to import tags into a specified database.

Request Parameters

• req.body.code: The code representing the database.
• req.body.data: The tags data to be imported.

Response

• If the import is successful, the API responds with a JSON object containing the imported tags.
• If the code is missing in the request or the specified database doesn’t exist, the API responds with a status code of 500 and an error message in JSON format.

Export Tags

Endpoint: POST /databases/export-tags

This endpoint allows you to export tags from a specified database.

Request Parameters

• req.body.code: The code representing the database.

Response

• If the export is successful, the API responds with a JSON object containing the exported tags.
• If the code is missing in the request or the specified database doesn’t exist, the API responds with a status code of 500 and an error message in JSON format.

Import Tags (Raw)

Endpoint: POST /databases/import-tags-raw

This endpoint allows you to import tags in raw format into a specified database.

Request Parameters

• req.body.code: The code representing the database.
• req.body.data: The raw tags data to be imported.

Response

• If the import is successful, the API responds with a JSON object containing the imported tags.
• If the code or data is missing in the request, the API responds with a status code of 500 and an error message in JSON format.

Collection Item CRUD Operations

Endpoint: POST /collections/{collectionId}/items

This endpoint allows you to perform CRUD operations on collection items.

Request Parameters

• req.params.collectionId: The ID of the collection.
• req.body: The data representing the collection item. The structure may vary depending on your application’s requirements.

Response

• If the operation is successful, the API responds with a JSON object containing the created, updated, or deleted collection item.
• If there is an error during the operation, the API responds with a status code of 500 and an error message in JSON format.

Endpoint: GET /collections/{collectionId}/items/{itemId}

This endpoint allows you to retrieve a specific collection item.

Request Parameters

• req.params.collectionId: The ID of the collection.
• req.params.itemId: The ID of the collection item.

Response

• If the item is found, the API responds with a JSON object containing the collection item.
• If the item or collection doesn’t exist, the API responds with a status code of 404 and an error message in JSON format.

Endpoint: PUT /collections/{collectionId}/items/{itemId}

This endpoint allows you to update a specific collection item.

Request Parameters

• req.params.collectionId: The ID of the collection.
• req.params.itemId: The ID of the collection item.
• req.body: The updated data for the collection item.

Response

• If the update is successful, the API responds with a JSON object containing the updated collection item.
• If there is an error during the update, the API responds with a status code of 500 and an error message in JSON format.

Endpoint: DELETE /collections/{collectionId}/items/{itemId}

This endpoint allows you to delete a specific collection item.

Request Parameters

• req.params.collectionId: The ID of the collection.
• req.params.itemId: The ID of the collection item.

Response

• If the deletion is successful, the API responds with a JSON object containing the deleted collection item.
• If there is an error during the deletion, the API responds with a status code of 500 and an error message in JSON format.

Tags CRUD Operations

Endpoint: POST /databases/{databaseId}/tags

This endpoint allows you to create a new tag within a specific database.

Request Parameters

• req.params.databaseId: The ID of the database.
• req.body: The data representing the tag. The structure may vary depending on your application’s requirements.

Response

• If the creation is successful, the API responds with a JSON object containing the created tag.
• If there is an error during the creation, the API responds with a status code of 500 and an error message in JSON format.

Endpoint: GET /databases/{databaseId}/tags/{tagId}

This endpoint allows you to retrieve a specific tag within a specific database.

Request Parameters

• req.params.databaseId: The ID of the database.
• req.params.tagId: The ID of the tag.

Response

• If the tag is found, the API responds with a JSON object containing the tag.
• If the tag doesn’t exist or the specified database doesn’t exist, the API responds with a status code of 404 and an error message in JSON format.

Endpoint: PUT /databases/{databaseId}/tags/{tagId}

This endpoint allows you to update a specific tag within a specific database.

Request Parameters

• req.params.databaseId: The ID of the database.
• req.params.tagId: The ID of the tag.
• req.body: The updated data for the tag.

Response

• If the update is successful, the API responds with a JSON object containing the updated tag.
• If there is an error during the update, the API responds with a status code of 500 and an error message in JSON format.

Endpoint: DELETE /databases/{databaseId}/tags/{tagId}

This endpoint allows you to delete a specific tag within a specific database.

Request Parameters

• req.params.databaseId: The ID of the database.
• req.params.tagId: The ID of the tag.

Response

• If the deletion is successful, the API responds with a JSON object containing the deleted tag.
• If there is an error during the deletion, the API responds with a status code of 500 and an error message in JSON format.

Please make sure to include the databaseId parameter when interacting with tags to ensure that the operations are performed within the context of the specified database.