As an external database service plugin provider (formerly SPI), you can create a service that allows Wix sites to access and manage data stored anywhere, as if it were hosted natively on Wix. By implementing this service plugin, your service can:
Learn more about service plugins.
Wix offers a variety of data management solutions to accommodate common user needs at different scales. This includes support for internal databases that are hosted directly on Wix, as well as external databases hosted outside the Wix ecosystem.
You can store and manage data directly on Wix using the Wix Data API. Wix also supports managing data hosted on external databases. The External Database Connections API allows Wix Data to communicate with an external database as if it were hosted directly on Wix. Wix offers several out-of-the-box external database integrations for common platforms such as Google Cloud Platform (GCP), Amazon Web Services (AWS), or Microsoft Azure. These integrations translate Wix Data requests into the external database's protocol, and translate the response back into a format that Wix APIs can read.
To allow Wix Data to communicate with any other data source, implement the External Database service plugin.
The External Database service plugin defines endpoints you can implement to integrate an external database with Wix. Wix Data calls these endpoints to access and manage the items and collections the external database contains. The endpoints descriptions specify what type of request Wix Data sends to each endpoint, and what type of response each endpoint is expected to return.
When the service is implemented and ready for use, you can make it available to users by creating a Wix app and configuring it with the details of your service. This tells Wix Data where your service is deployed. After installing your app on their sites, site admins can use the Wix Data APIs to access and interact with the external database as if it were hosted on Wix.
While you aren't required to implement all the endpoints in this service plugin, make sure to implement at least the following endpoints to provide basic functionality:
Your service can accommodate many scenarios that require Wix Data to communicate with external databases. These might include:
To enable Wix Data to communicate with your service:
Create an app in your Wix Studio workspace.
Go to Extensions in your app's dashboard.
Click Create Extension.
Find and select External Database Provider and click Create.
If it has not been set before, set up an app namespace. This is a unique identifier for your app that, once set, can't be changed. It is added as a prefix to the user's external collection names.
Use the built-in JSON editor to provide your extension’s configuration details. Make sure to include all the required fields as they appear in the table below. Once you're done, click Save.
Name | Type | Description |
---|---|---|
namespace | String | Required. A prefix for all the collections your application retrieves. It must be identical to your app namespace. |
uriConfig | Object | The URI configuration object. |
uriConfig.baseUri | String | Required. Base URI where your service is deployed. Wix Data uses this URI to call your service's endpoints. |
componentName | String | A unique name for this component. This is an internal name that appears in the app dashboard only. |
For example:
{
"namespace": "@your-account-name/your-app-name",
"uriConfig": {
"baseUri": "https://my-external-db-collections-service.com"
},
"componentName": "myExternalCollections"
}
Term | Definition |
---|---|
Collection | A schema that determines the structure of data items to be stored. The schema defines the fields each item contains and the data type of each field. |
Item | A single data entry in a collection. |
External Database | A database hosted by an external service outside of Wix. |
External Database Service Provider | A 3rd-party service that implements an interface to allow Wix Data to interact with an external database. |
This article presents some sample use cases your service might support. You are not limited to these exact flows, but they can serve as good starting points to help you plan your external database integration.
Note: This sample flow requires the implementation of at least the basic functionality endpoints of this service plugin.
A real-estate agency stores information about the properties it manages in an external database. The agency has a Wix site and wants to make its properties available to its visitors. The agency implements the relevant endpoints of the External Database Service Plugin and hosts them at the https://www.<example-domain>.com
base URL. It then creates a Wix app, configures it with the details of the service, and installs the app on its site. The site can then interact with the external database like this:
On a dedicated search page, a site visitor searches for relevant properties with the following search and sorting criteria:
Based on the visitor's criteria, Wix Data automatically sends a Query Data Items request to the service endpoint hosted at https://www.<example-domain>.com/v3/items/query
. The request body looks like this:
{
"collectionId": "SpringfieldProperties",
"query": {
"filter": {
"price": {
"$gte": 550,
"$lte": 700
}
},
"sort": [
{
"fieldName": "price"
}
],
"fields": [],
"paging": {
"limit": 3,
"offset": 0
}
},
"includeReferencedItems": [],
"consistentRead": false,
"returnTotalCount": false
}
The endpoint responds with the relevant items, filtered and sorted as specified in the query. For example:
{
"items": [
{
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"address": "742 Evergreen Terrace",
"floor": 4,
"aptNum": 2,
"numBedrooms": 2,
"numBaths": 1,
"price": 600,
"pets": true,
"airConditioning": false
},
{
"_id": "e831385d-d067-4905-a98a-456f5a526ca2",
"address": "247 Foreverblue Blvd",
"floor": 2,
"aptNum": 2,
"numBedrooms": 1,
"numBaths": 1,
"price": 680,
"pets": false,
"airConditioning": true
}
],
"pagingMetadata": {
"cursors": {
"next": "0O52kwmAcT",
"prev": "omZq6gTpR9"
}
}
}
The site receives the data as if it were stored in a native Wix Data collection. It then parses the response and displays the results to the visitor.
Note: This sample flow requires the implementation of the following service plugin endpoints:
A large employment agency maintains its job listings in an external database. The agency has several branches. Each branch operates in a different area and has its own Wix site.
To enable each branch to independently access and manage the job listings stored in the database, the agency implements the External Database service plugin and hosts it on the https://www.<example-domain>.com
base URL. It then creates a private app and configures it with the details of the service. Each branch installs the app on its site to gain independent access to the database. Site visitors can then query, sort, and filter relevant listings on the site branch most relevant to them.
In this flow, a site visitor searches for open kitchen staff positions on a branch's site. After finding a relevant position, they browse for other listings by the same employer. Once filled, the branch closes the position.
On a dedicated search page, a site visitor searches for open listings using the following search and sorting criteria:
Based on these preferences, Wix Data automatically sends a Query Data Items request to the service endpoint hosted at https://www.<example-domain>.com/v3/items/query
. The request body looks like this:
{
"collectionId": "northUtahJobs",
"query": {
"filter": {
"jobTitle": "kitchenStaff",
"status": "OPEN"
},
"sort": [
{
"fieldName": "_updatedDate",
"order": "DESC"
}
],
"paging": {
"limit": 5,
"offset": 0
},
"fields": [
"_id",
"jobTitle",
"employer",
"address",
"salaryHourly",
"_updatedDate"
] // The details of the listing to retrieve
},
"includeReferencedItems": [
{
"fieldKey": "employer"
}
],
"consistentRead": false,
"returnTotalCount": true
}
The endpoint responds with the relevant listings, filtered and sorted as specified in the query. For example:
{
"items": [
{
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"jobTitle": "kitchenStaff",
"employer": "hellsKitchen",
"address": "616 Old Nick Road, Salt Lake City, Utah",
"salaryHourly": 10,
"_updatedDate": {
"$date": "2021-02-03T04:05:06Z"
},
"employer": {
"_id": "faa17edb-2d88-488d-8e95-24b9364c3284",
"name": "hellsKitchen",
"address": "616 Old Nick Road, Salt Lake City, Utah",
"numEmployees": "14",
"reputation": 4.4
}
},
{
"_id": "528a0b23-d6d8-464a-82af-09e0c00f56b0",
"jobTitle": "kitchenStaff",
"employer": "Joe's Magic Burgers",
"address": "23 Hawkins Street, Arborville, Utah",
"salaryHourly": 9.5,
"_updatedDate": {
"$date": "2021-02-02T12:53:01Z"
},
"employer": {
"_id": "faa17edb-2d88-488d-8e95-24b9364c3284",
"name": "Joe's Magic Burgers",
"address": "46 Horseshoe Lane, Utah",
"numEmployees": "38",
"reputation": 4.9
}
}
],
"pagingMetadata": {
"total": 2
}
}
The site receives the data as if it were stored in a native Wix Data collection. It then parses the response and displays the results to the visitor.
One of the listings retrieved by Wix Data is for a position offered by Hell's Kitchen. The visitor wants to check which other positions Hell's Kitchen offers. To do that, Wix Data sends a Query Referenced Data Items request to the service endpoint hosted at https://www.<example-domain>.com/v3/items/query-referenced
. For each position listed by this employer, the visitor is interested in the job title, work address, hourly salary, and position status. The request looks like this:
{
"collectionId": "employers",
"referringItemIds": ["faa17edb-2d88-488d-8e95-24b9364c3284"], // Hell's Kitchen's ID
"referencedItemIds": [],
"order": "ASC",
"referringFieldKey": "positions",
"consistentRead": false,
"fieldsToReturn": ["_id", "jobTitle", "address", "hourlySalary", "status"],
"returnTotalCount": false,
"includeReferencedItems": true
}
The endpoint responds with all the job positions offered by Hell's Kitchen, filtered and sorted as specified in the query. For example:
{
"items": [
{
"referringItemId": "faa17edb-2d88-488d-8e95-24b9364c3284",
"referencedItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItem": {
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"jobTitle": "kitchenStaff",
"address": "616 Old Nick Road, Utah",
"hourlySalary": "10",
"status": "OPEN"
}
},
{
"referringItemId": "faa17edb-2d88-488d-8e95-24b9364c3284",
"referencedItemId": "d345e77c-4f6b-5g60-4fh7-d6b9dd70kf9",
"referencedItem": {
"_id": "d345e77c-4f6b-5g60-4fh7-d6b9dd70kf9",
"jobTitle": "shiftManager",
"address": "616 Old Nick Road, Utah",
"hourlySalary": "14.5",
"status": "OPEN"
}
},
{
"referringItemId": "faa17edb-2d88-488d-8e95-24b9364c3284",
"referencedItemId": "mir0958c-mfe8-kdo9-jf71-mfe0kfik4lkfp",
"referencedItem": {
"_id": "mir0958c-mfe8-kdo9-jf71-mfe0kfik4lkfp",
"jobTitle": "hostPerson",
"address": "616 Old Nick Road, Utah",
"hourlySalary": "9.5",
"status": "HIRED"
}
}
// Additional positions
],
"pagingMetadata": {}
}
The site receives the data as if it were stored in a native Wix Data collection. It parses the data, filters for positions whose status
is OPEN
, and displays the results to the visitor.
The Hell's Kitchen branch on Old Nick Road hires a new employee for the kitchen staff position. The employment agency's branch then closes the position. To do that, Wix Data sends an Update Data Items request to the service endpoint hosted at https://www.<example-domain>.com/v3/items/update
to update the position's status as HIRED
. The request looks like this:
{
"collectionId": "northUtahJobs",
"items": [
{
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"jobTitle": "kitchenStaff",
"employer": "hellsKitchen",
"address": "616 Old Nick Road, Utah",
"salaryHourly": 10,
"status": "HIRED",
"_updatedDate": {
"$date": "2021-02-15T15:22:36Z"
}
}
]
}
The endpoint responds with the updated item:
{
"results": [
{
"item": {
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"jobTitle": "kitchenStaff",
"employer": "hellsKitchen",
"address": "616 Old Nick Road, Utah",
"salaryHourly": 10,
"status": "HIRED",
"_updatedDate": {
"$date": "2021-02-15T15:22:36Z"
}
}
}
]
}
Some endpoints in the external database service plugin must respond with errors if the request is invalid or cannot be successfully fulfilled. In such cases, your service must respond with an error specific to the particular issue in the request.
Each error type conforms to a predefined structure. It includes an error code, an error message, and a data object with additional error handling information. In addition, each error type has a corresponding HTTP code.
Error objects have the following properties:
Field | Type | Description |
---|---|---|
errorCode | String | A code that indicates why the request failed. |
errorMessage | String | A human-readable error message. |
data | Object | Additional error data specific to the error type. |
For example, your service might receive a request to query a collection that does not exist. In this case, your service must respond with the relevant error code, a descriptive message, and a data object with the collectionId
of the collection that was not found. This type of error looks like this:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errorCode": "COLLECTION_NOT_FOUND",
"errorMessage": "The requested collection was not found.",
"data": {
"collectionId": "catPictures"
}
}
The following table lists the errors your service must return based on the issue in the request:
Error Code | HTTP Status Code | Description |
---|---|---|
ITEM_NOT_FOUND | Not Found (404) | Item was not found in the specified collection. See corresponding data object. |
ITEM_ALREADY_EXISTS | Conflict (409) | Item with the same id already exists in the specified collection. See corresponding data object |
COLLECTION_NOT_FOUND | Not Found (404) | Collection was not found. See corresponding data object. |
COLLECTION_ALREADY_EXISTS | Conflict (409) | Collection with the same id already exists. See corresponding data object. |
COLLECTION_CHANGE_NOT_SUPPORTED | Bad Request (400) | The service does not allow modifications to the specified collection. The corresponding data object lists the fields that caused the error. |
REFERENCE_NOT_FOUND | Not Found (404) | Reference was not found for the specified item. See corresponding data object. |
REFERENCE_ALREADY_EXISTS | Conflict (409) | Reference already exists for the specified item. See corresponding data object. |
VALIDATION_ERROR | Bad Request (400) | One or more fields in the request are not valid. The corresponding data object lists the validation errors caused by the request. |
BAD_REQUEST | Bad Request (400) | Generic error indicating an invalid request. Use the errorMessage field to provide more information. |
Each error object type has a unique data
property structure. This section details the data
structure associated with each type.
Field | Type | Description |
---|---|---|
itemId | String | ID of the item that was not found. |
{
"errorCode": "ITEM_NOT_FOUND",
"errorMessage": "The requested item was not found.",
"data": {
"itemId": "c285e77c-a86b-4361-a55f-c6b934d70187"
}
}
Field | Type | Description |
---|---|---|
itemId | String | ID of the item that already exists. |
{
"errorCode": "ITEM_ALREADY_EXISTS",
"errorMessage": "The item already exists in the collection.",
"data": {
"itemId": "c2f5e77c-a86b-4361-a55f-c6b934d70187"
}
}
Field | Type | Description |
---|---|---|
collectionId | String | ID of the collection that was not found. |
{
"errorCode": "COLLECTION_NOT_FOUND",
"errorMessage": "The requested collection was not found.",
"data": {
"collectionId": "cities"
}
}
Field | Type | Description |
---|---|---|
collectionId | String | ID of the collection that already exists. |
{
"errorCode": "COLLECTION_ALREADY_EXISTS",
"errorMessage": "The specified collection already exists.",
"data": {
"collectionId": "countries"
}
}
This data
property of this error lists all fields that the request attempted, but failed, to change. Each such attempt causes an individual Collection Change Not Supported error.
Field | Type | Description |
---|---|---|
errors | Array of collection change not supported errors | An array of unsupported collection change errors caused by the request. One error is produced for each unmodifiable field the caller attempts to change. |
Each individual Collection Change not Supported error has the following structure:
Field | Type | Description |
---|---|---|
fieldKey | String | Key of the field that cannot be changed. |
message | String | Error message explaining why the field cannot be changed. |
{
"errorCode": "COLLECTION_CHANGE_NOT_SUPPORTED",
"errorMessage": "Some fields in this collection cannot be changed.",
"data": {
"errors": [
{
"fieldKey": "firstName",
"message": "This field cannot be changed."
},
{
"fieldKey": "lastName",
"message": "This field cannot be changed."
}
]
}
}
Field | Type | Description |
---|---|---|
referringItemId | String | ID of the referring item. |
referencedItemId | String | ID of the referenced item. |
{
"errorCode": "REFERENCE_NOT_FOUND",
"errorMessage": "The requested reference was not found.",
"data": {
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}
}
Field | Type | Description |
---|---|---|
referringItemId | String | ID of the referring item. |
referencedItemId | String | ID of the referenced item. |
{
"errorCode": "REFERENCE_ALREADY_EXISTS",
"errorMessage": "The requested reference already exists for the referring item.",
"data": {
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}
}
This data
property of this error lists all individual validation violations caused by the request.
Field | Type | Description |
---|---|---|
violations | Array of validation violations. | An array of all validation violations caused by the request. |
Each individual validation violation has the following structure:
Field | Type | Description |
---|---|---|
fieldPath | String | Path to the invalid field. |
rejectedValue | String | The invalid value. |
message | String | Error message that describes the violation. |
{
"errorCode": "VALIDATION_ERROR",
"errorMessage": "Some fields contain invalid values.",
"data": {
"violations": [
{
"fieldPath": "userDateOfBirth",
"rejectedValue": "16-12-1994",
"message": "Invalid value for this field. See documentation for valid field values."
},
{
"fieldPath": "userImage",
"rejectedValue": "https://mediaa.wix.com/6acbb8_7a7bd9193ffc4130ab8ff74f5dcedf8a.jpg",
"message": "Invalid value for this field. See documentation for valid field values."
}
]
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of items based on the provided filtering, sorting, and paging preferences.
See API Query Language for more information about handling data queries.
ID of the collection to query.
Query preferences. See API Query Language for information about handling data queries.
Fields for which to include the full referenced items in the query's results, rather than just their IDs. Returned items are sorted in ascending order by the creation date of the reference. If the field being querried is a multi-reference field and the array is empty, the response does not return any items.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up-to-date even immediately after an update. Applicable if the external database is eventually consistent.
When true
, the query response must include the total number of items that match the query.
Retrieved items.
Pagination information.
curl POST https://external-db.example.com/v3/items/query \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"query": {
"filter": {
},
"sort": [],
"paging": {
"limit": 50,
"offset": 0
},
"fields": []
},
"includeReferencedItems": [],
"consistentRead": false,
"returnTotalCount": true
}'
{
"items": [
{
"name": "New York",
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"population": 8300000.0,
"country": "US",
"isCapital": false
}
],
"pagingMetadata": {
"total": 1
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Counts the number of items in the specified data collection that match the filtering preferences.
ID of the collection to query.
Filter to specify which items to count. See API Query Language for more information about handling data queries.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up-to-date even immediately after an update. Applicable if the external database is eventually consistent.
Number of items that match the query.
curl POST https://external-db.example.com/v3/items/count \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"filter": {
"country": "US"
},
"consistentRead": false
}'
{
"totalCount": 42
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Runs an aggregation query on the specified data collection and returns the resulting list of items.
ID of the collection on which to run the aggregation.
Filter to apply to the collection's data before aggregation. See API Query Language for more information about handling data queries.
Aggregation to apply to the data.
Filter to apply to the processed data after aggregation. See API Query Language for more information about handling data queries.
Sorting configuration.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up-to-date even immediately after an update. Applicable if the external database is eventually consistent.
When true
, the query response must include the total number of items that match the query.
Aggregation results. Each result must contain a field for each groupingFields
value, and a field for each operations.resultFieldName
value.
Paging information.
Aggregation request with an initial filter, aggregation operations, and a final filter.
curl POST https://external-db.example.com/v3/items/aggregate \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"initialFilter": {
"isCapital": false
},
"aggregation": {
"groupingFields": ["country"],
"operations": [{
"resultFieldName": "sumPopulation",
"sum": {
"itemFieldName": "population"
}
}, {
"resultFieldName": "countOfCities",
"itemCount": {
}
}]
},
"finalFilter": {
"countOfCities": {
"$gt": 5.0
}
},
"sort": [{
"fieldName": "sumPopulation",
"order": "ASC"
}],
"paging": {
"limit": 50,
"offset": 0
},
"consistentRead": false,
"returnTotalCount": true
}'
{
"items": [
{
"country": "US",
"sumPopulation": 2000000.0,
"countOfCities": 25.0
},
{
"country": "CA",
"sumPopulation": 1000000.0,
"countOfCities": 10.0
}
],
"pagingMetadata": {
"total": 2
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of distinct values for a given field for all items that match the query, without duplicates.
As with the Query Data Items endpoint, this endpoint retrieves items based on the filtering, sorting, and paging preferences provided.
However, the Query Distinct Values endpoint doesn't return the full items that match the query. Rather, for items that match the query, it returns all unique values in the field specified in fieldName
. If more than one item has the same value in that field, that value appears only once.
See API Query Language for more information about handling data queries.
ID of the collection to query.
Filter to apply to the collection's data before aggregation. See API Query Language for more information about handling data queries.
Item field name for which to return all distinct values.
Order to by which to sort the results. Valid values are ASC
and DESC
.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up-to-date even immediately after an update. Applicable if the external database is eventually consistent.
When true
, the query response must include the total number of items that match the query.
List of distinct values contained in the field specified in fieldName
. Values can be of any JSON type.
If the field is an array, values must be unwound, independent values. For example, if the field name contains ["a", "b", "c"]
, the result must contain "a"
, "b"
and "c"
as separate values.
Paging information.
curl POST https://external-db.example.com/v3/items/query-distinct-values \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"fieldName": "country",
"order": "ASC",
"paging": {
"limit": 50,
"offset": 0
},
"consistentRead": false,
"returnTotalCount": false
}'
{
"distinctValues": ["US", "CA"],
"pagingMetadata": {}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Adds one or more items to a collection.
A data item object contains the _id
and _owner
fields. The response array must include the same items that were inserted, and each returned item must be added the _createdDate
and _updatedDate
fields.
However, data items can also be inserted without an _id
field. In that case, it is the service provider's responsibility to generate a unique ID for each item.
ID of the collection in which to insert the items.
Items to insert.
Response must include either the inserted item or an error.
curl POST https://external-db.example.com/v3/items/insert \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"items": [{
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"name": "New York",
"_owner": "facda016-24ef-4909-a90e-70687f17f658"
}]
}'
{
"results": [
{
"item": {
"name": "New York",
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"_owner": "facda016-24ef-4909-a90e-70687f17f658",
"_createdDate": {
"$date": "2021-01-02T03:04:05Z"
},
"_updatedDate": {
"$date": "2021-01-02T03:04:05Z"
}
}
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates one or more items in a collection. Items must be completely replaced.
The response array must include the same items that were updated, and each returned item must be added the _createdDate
and _updatedDate
fields.
ID of the collection in which to update the items.
Items to update.
Response must include either the updated item or an error.
curl POST https://external-db.example.com/v3/items/update \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"items": [{
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"name": "New York",
"_owner": "facda016-24ef-4909-a90e-70687f17f658"
}]
}'
{
"results": [
{
"item": {
"name": "New York",
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"_owner": "facda016-24ef-4909-a90e-70687f17f658",
"_createdDate": {
"$date": "2021-01-02T03:04:05Z"
},
"_updatedDate": {
"$date": "2021-04-05T06:07:08Z"
}
}
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes one or more items from a collection. The response object must contain the removed item.
ID of the collection from which to remove items.
IDs of items to remove.
Response must include either the removed item or an error.
curl POST https://external-db.example.com/v3/items/remove \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"itemIds": ["c285e77c-a86b-4361-a55f-c6b934d70187"]
}'
{
"results": [
{
"item": {
"name": "New York",
"_id": "c285e77c-a86b-4361-a55f-c6b934d70187",
"_owner": "facda016-24ef-4909-a90e-70687f17f658",
"_createdDate": {
"$date": "2021-01-02T03:04:05Z"
},
"_updatedDate": {
"$date": "2021-04-05T06:07:08Z"
}
}
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes all items from a collection.
ID of the collection from which to remove all items.
curl POST https://external-db.example.com/v3/items/truncate \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities"
}'
{}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves the items referenced in the specified field of a referring item. Reference fields refer to items that exist in different collections. Implement this endpoint so callers can retrieve the full details of the referenced items.
This service plugin supports item multi-references, which means that data collections can have many-to-many relationships with other collections. For example, consider a scenario where a Movies collection includes a multi-reference Actors field, which might refer to several Actor items in an Actors collection. Users can therefore query the Movies collection to retrieve the Actor items referenced in each Movie item.
Notes:
ID of the collection to query.
IDs of the referring items. If the array is empty, return results for all referring items.
IDs of the referenced items. If the array is empty, return all referenced items for the referring items.
Order to by which to sort the results. Valid values are ASC
and DESC
.
Field ID to query in the referring collection.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up-to-date even immediately after an update. Applicable if the external database is eventually consistent.
Fields to return in the referenced item. If the array is empty or not provided, all fields in the referenced item are returned.
When true
, the response includes the total number of the items that match the query.
When true
, the response includes the full referenced items. When false
, only the IDs of referenced items be returned.
Offset-based paging
Cursor-based paging
Retrieved references.
Paging information.
For a single data item, query and return a specified referenced item.
curl POST https://external-db.example.com/v3/items/query-referenced \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"referringItemIds": ["c285e77c-a86b-4361-a55f-c6b934d70187"],
"referencedItemIds": ["faa17edb-2d88-488d-8e95-24b9364c3284"],
"order": "ASC",
"referringFieldKey": "pointsOfInterest",
"paging": {
"limit": 1,
"offset": 0
},
"consistentRead": false,
"fieldsToReturn": [],
"returnTotalCount": false,
"includeReferencedItems": false
}'
{
"items": [
{
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}
],
"pagingMetadata": {}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Inserts one or more item references into a referring field of the specified item.
ID of the referring collection.
Field ID of the field in the referring collection to insert references into.
References to insert.
Response must include either the inserted reference or an error.
Creates a reference from one item to another.
curl POST https://external-db.example.com/v3/items/insert-references \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"referringFieldKey": "pointsOfInterest",
"references": [{
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}]
}'
{
"results": [
{
"reference": {
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes one or more item references from a referring field of the specified item.
ID of the referring collection.
Field ID of the field in the referring collection to remove references from.
References to remove.
Response must include either the removed reference or an error.
curl POST https://external-db.example.com/v3/items/remove-references \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"referringFieldKey": "pointsOfInterest",
"references": [{
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}]
}'
{
"results": [
{
"reference": {
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of data collections and their details.
When collectionIds
is empty, all existing collections are returned.
If a specified collection does not exist, that collection can be ignored.
IDs of collections to retrieve. If empty, all available collections are retrieved.
List of the retrieved collections.
curl POST https://external-db.example.com/v3/collections/get \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionIds": []
}'
{
"collections": [
{
"id": "cities",
"displayName": "Cities",
"fields": [
{
"key": "_id",
"displayName": "ID",
"description": "The ID of the document",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "LT", "GT", "LTE", "GTE"]
},
"encrypted": false
},
{
"key": "name",
"displayName": "Name",
"description": "The name of the city",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "STARTS_WITH"]
},
"encrypted": false
},
{
"key": "country",
"displayName": "Country",
"description": "Country code",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ"]
},
"encrypted": false
},
{
"key": "pointsOfInterest",
"displayName": "Points of interest",
"type": "MULTI_REFERENCE",
"multiReferenceOptions": {
"referencedCollectionId": "pointsOfInterest"
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created date",
"description": "The date when the document was created",
"type": "DATETIME",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated date",
"description": "The date when the document was last updated",
"type": "DATETIME",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
}
],
"capabilities": {
"dataOperations": ["QUERY", "COUNT"]
},
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"pagingMode": "OFFSET"
},
{
"id": "pointsOfInterest",
"displayName": "Points of interest",
"fields": [
{
"key": "_id",
"displayName": "ID",
"description": "The ID of the document",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "LT", "GT", "LTE", "GTE"]
},
"encrypted": false
},
{
"key": "name",
"displayName": "Name",
"description": "The name of the city",
"type": "TEXT",
"encrypted": false
}
],
"capabilities": {
"dataOperations": ["QUERY", "COUNT"]
},
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"pagingMode": "OFFSET"
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a new data collection.
Details of the collection to create.
Details of the created collection.
curl POST https://external-db.example.com/v3/collections/create \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collection": {
"id": "cities",
"displayName": "Cities",
"fields": [{
"key": "name",
"displayName": "Name",
"description": "The name of the city",
"type": "TEXT",
"encrypted": false
}, {
"key": "country",
"displayName": "Country",
"description": "Country code",
"type": "TEXT",
"encrypted": false
}, {
"key": "pointsOfInterest",
"displayName": "Points of interest",
"type": "MULTI_REFERENCE",
"multiReferenceOptions": {
"referencedCollectionId": "pointsOfInterest",
"referencedCollectionFieldKey": "cities",
"referencedCollectionFieldDisplayName": "Cities"
},
"encrypted": false
}, {
"key": "_id",
"displayName": "ID",
"type": "TEXT",
"encrypted": false
}, {
"key": "_createdDate",
"displayName": "Created Date",
"type": "DATETIME",
"encrypted": false
}, {
"key": "_updatedDate",
"displayName": "Updated Date",
"type": "DATETIME",
"encrypted": false
}, {
"key": "_owner",
"displayName": "Owner",
"type": "TEXT",
"encrypted": false
}],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"pagingMode": "UNKNOWN_PAGING_MODE"
}
}'
{
"collection": {
"id": "cities",
"displayName": "Cities",
"fields": [
{
"key": "_id",
"displayName": "ID",
"description": "The ID of the document",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "LT", "GT", "LTE", "GTE"]
},
"encrypted": false
},
{
"key": "name",
"displayName": "Name",
"description": "The name of the city",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "STARTS_WITH"]
},
"encrypted": false
},
{
"key": "country",
"displayName": "Country",
"description": "Country code",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ"]
},
"encrypted": false
},
{
"key": "pointsOfInterest",
"displayName": "Points of interest",
"type": "MULTI_REFERENCE",
"multiReferenceOptions": {
"referencedCollectionId": "pointsOfInterest"
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created date",
"description": "The date when the document was created",
"type": "DATETIME",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated date",
"description": "The date when the document was last updated",
"type": "DATETIME",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
},
{
"key": "_owner",
"type": "TEXT",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
}
],
"capabilities": {
"dataOperations": ["QUERY", "COUNT"]
},
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"pagingMode": "OFFSET"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates the structure of an existing data collection.
Some parameters, such as capabilities
and pagingMode
, are determined by the service provider. If the collection passed in the request contains these parameters, their values must be ignored. However, these fields must be included in the response collection with relevant values.
Updated structure details for the specified collection.
Updated collection details.
curl POST https://external-db.example.com/v3/collections/update \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collection": {
"id": "cities",
"displayName": "Cities",
"fields": [{
"key": "name",
"displayName": "Name",
"description": "The name of the city",
"type": "TEXT",
"encrypted": false
}, {
"key": "country",
"displayName": "Country",
"description": "Country code",
"type": "TEXT",
"encrypted": false
}, {
"key": "pointsOfInterest",
"displayName": "Points of interest",
"type": "MULTI_REFERENCE",
"multiReferenceOptions": {
"referencedCollectionId": "pointsOfInterest",
"referencedCollectionFieldKey": "cities",
"referencedCollectionFieldDisplayName": "Cities"
},
"encrypted": false
}, {
"key": "_id",
"displayName": "ID",
"type": "TEXT",
"encrypted": false
}, {
"key": "_createdDate",
"displayName": "Created Date",
"type": "DATETIME",
"encrypted": false
}, {
"key": "_updatedDate",
"displayName": "Updated Date",
"type": "DATETIME",
"encrypted": false
}, {
"key": "_owner",
"displayName": "Owner",
"type": "TEXT",
"encrypted": false
}],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"pagingMode": "UNKNOWN_PAGING_MODE"
}
}'
{
"collection": {
"id": "cities",
"displayName": "Cities",
"fields": [
{
"key": "_id",
"displayName": "ID",
"description": "The ID of the document",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "LT", "GT", "LTE", "GTE"]
},
"encrypted": false
},
{
"key": "name",
"displayName": "Name",
"description": "The name of the city",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ", "STARTS_WITH"]
},
"encrypted": false
},
{
"key": "country",
"displayName": "Country",
"description": "Country code",
"type": "TEXT",
"capabilities": {
"sortable": true,
"queryOperators": ["EQ"]
},
"encrypted": false
},
{
"key": "pointsOfInterest",
"displayName": "Points of interest",
"type": "MULTI_REFERENCE",
"multiReferenceOptions": {
"referencedCollectionId": "pointsOfInterest"
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created date",
"description": "The date when the document was created",
"type": "DATETIME",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated date",
"description": "The date when the document was last updated",
"type": "DATETIME",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
},
{
"key": "_owner",
"type": "TEXT",
"capabilities": {
"sortable": false,
"queryOperators": []
},
"encrypted": false
}
],
"capabilities": {
"dataOperations": ["QUERY", "COUNT"]
},
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"pagingMode": "OFFSET"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a data collection.
ID of the collection to delete.
curl POST https://external-db.example.com/v3/collections/delete \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities"
}'
{}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Lists the global capabilities the external database supports.
Whether the external database supports creating new collections, updating the structure of existing collections, or deleting them.
Field types the external database supports. This field only applies when supportsCollectionModifications
is true.
curl POST https://external-db.example.com/v3/capabilities/get \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
}'
{
"supportsCollectionModifications": true,
"supportedFieldTypes": ["TEXT", "DATETIME", "NUMBER", "BOOLEAN"]
}