About the External Database Service Plugin

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:

  • Make external business data available to Wix sites.
  • Make an external database available to Wix site owners to store their business data.

Learn more about service plugins.

Managing data with Wix

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.

Become an external database service provider

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.

Provide basic functionality

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:

  • Get Capabilities: This endpoint lets Wix Data determine which capabilities are supported by the external database.
  • List Collections: This endpoint enables Wix Data to view the collections stored in the external database.
  • Query Data Items: This endpoint enables Wix Data to query items in an external collection.

Use Cases

Your service can accommodate many scenarios that require Wix Data to communicate with external databases. These might include:

  • A business that wants to make its data available for Wix site owners.
  • A Wix site owner whose data is stored in an external database and wants to query and display that data on their site.
  • A Wix app developer who wants to implement ready-for-use external database integrations for specific database services.
  • A growing business that wants to store its Wix collections on an external cloud service to scale as needed.

Configuration

To enable Wix Data to communicate with your service:

  1. Create an app in your Wix Studio workspace.

  2. Go to Extensions in your app's dashboard.

  3. Click Create Extension.

  4. Find and select External Database Provider and click Create.

  5. 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. wix app namespace modal

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

NameTypeDescription
namespaceStringRequired. A prefix for all the collections your application retrieves. It must be identical to your app namespace.
uriConfigObjectThe URI configuration object.
uriConfig.baseUriStringRequired. Base URI where your service is deployed. Wix Data uses this URI to call your service's endpoints.
componentNameStringA unique name for this component. This is an internal name that appears in the app dashboard only.

For example:

Copy
{ "namespace": "@your-account-name/your-app-name", "uriConfig": { "baseUri": "https://my-external-db-collections-service.com" }, "componentName": "myExternalCollections" }

Terminology

TermDefinition
CollectionA 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.
ItemA single data entry in a collection.
External DatabaseA database hosted by an external service outside of Wix.
External Database Service ProviderA 3rd-party service that implements an interface to allow Wix Data to interact with an external database.
Did this help?

Sample Flows

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.

Query real-estate properties in an external database

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:

  1. On a dedicated search page, a site visitor searches for relevant properties with the following search and sorting criteria:

    • Locality: Springfield
    • Max number of rooms: 3
    • Price range: $550-$700
    • Sort: Low-to-high
    • Page limit: 3
  2. 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:

    Copy
    { "collectionId": "SpringfieldProperties", "query": { "filter": { "price": { "$gte": 550, "$lte": 700 } }, "sort": [ { "fieldName": "price" } ], "fields": [], "paging": { "limit": 3, "offset": 0 } }, "includeReferencedItems": [], "consistentRead": false, "returnTotalCount": false }
  3. The endpoint responds with the relevant items, filtered and sorted as specified in the query. For example:

    Copy
    { "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.

Manage local job positions with an app

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.

  1. On a dedicated search page, a site visitor searches for open listings using the following search and sorting criteria:

    • Locality: North Utah
    • Sector: Restaurants
    • Position: Kitchen Staff
    • Show listing details: Job Title, Employer, Address, Hourly Salary
    • Sort: New-to-old
    • Page limit: 5
  2. 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:

    Copy
    { "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:

    Copy
    { "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 } }
  3. 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.

  4. 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:

    Copy
    { "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:

    Copy
    { "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": {} }
  5. 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.

  6. 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:

    Copy
    { "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:

    Copy
    { "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" } } } ] }
Did this help?

Error Types in the External Database Collections Service Plugin

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.

Error structure

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:

FieldTypeDescription
errorCodeStringA code that indicates why the request failed.
errorMessageStringA human-readable error message.
dataObjectAdditional 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:

Copy
HTTP/1.1 404 Not Found Content-Type: application/json { "errorCode": "COLLECTION_NOT_FOUND", "errorMessage": "The requested collection was not found.", "data": { "collectionId": "catPictures" } }

Types of errors

The following table lists the errors your service must return based on the issue in the request:

Error CodeHTTP Status CodeDescription
ITEM_NOT_FOUNDNot Found (404)Item was not found in the specified collection. See corresponding data object.
ITEM_ALREADY_EXISTSConflict (409)Item with the same id already exists in the specified collection. See corresponding data object
COLLECTION_NOT_FOUNDNot Found (404)Collection was not found. See corresponding data object.
COLLECTION_ALREADY_EXISTSConflict (409)Collection with the same id already exists. See corresponding data object.
COLLECTION_CHANGE_NOT_SUPPORTEDBad 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_FOUNDNot Found (404)Reference was not found for the specified item. See corresponding data object.
REFERENCE_ALREADY_EXISTSConflict (409)Reference already exists for the specified item. See corresponding data object.
VALIDATION_ERRORBad 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_REQUESTBad Request (400)Generic error indicating an invalid request. Use the errorMessage field to provide more information.

Error data object structures

Each error object type has a unique data property structure. This section details the data structure associated with each type.

Item not found

FieldTypeDescription
itemIdStringID of the item that was not found.
Copy
{ "errorCode": "ITEM_NOT_FOUND", "errorMessage": "The requested item was not found.", "data": { "itemId": "c285e77c-a86b-4361-a55f-c6b934d70187" } }

Item already exists

FieldTypeDescription
itemIdStringID of the item that already exists.
Copy
{ "errorCode": "ITEM_ALREADY_EXISTS", "errorMessage": "The item already exists in the collection.", "data": { "itemId": "c2f5e77c-a86b-4361-a55f-c6b934d70187" } }

Collection not found

FieldTypeDescription
collectionIdStringID of the collection that was not found.
Copy
{ "errorCode": "COLLECTION_NOT_FOUND", "errorMessage": "The requested collection was not found.", "data": { "collectionId": "cities" } }

Collection already exists

FieldTypeDescription
collectionIdStringID of the collection that already exists.
Copy
{ "errorCode": "COLLECTION_ALREADY_EXISTS", "errorMessage": "The specified collection already exists.", "data": { "collectionId": "countries" } }

Collection changes not supported

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.

FieldTypeDescription
errorsArray of collection change not supported errorsAn array of unsupported collection change errors caused by the request. One error is produced for each unmodifiable field the caller attempts to change.

Collection change not supported

Each individual Collection Change not Supported error has the following structure:

FieldTypeDescription
fieldKeyStringKey of the field that cannot be changed.
messageStringError message explaining why the field cannot be changed.
Copy
{ "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." } ] } }

Reference not found

FieldTypeDescription
referringItemIdStringID of the referring item.
referencedItemIdStringID of the referenced item.
Copy
{ "errorCode": "REFERENCE_NOT_FOUND", "errorMessage": "The requested reference was not found.", "data": { "referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187", "referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284" } }

Reference already exists

FieldTypeDescription
referringItemIdStringID of the referring item.
referencedItemIdStringID of the referenced item.
Copy
{ "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" } }

Validation violations

This data property of this error lists all individual validation violations caused by the request.

FieldTypeDescription
violationsArray of validation violations.An array of all validation violations caused by the request.

Validation violation

Each individual validation violation has the following structure:

FieldTypeDescription
fieldPathStringPath to the invalid field.
rejectedValueStringThe invalid value.
messageStringError message that describes the violation.
Copy
{ "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." } ] } }
Did this help?

POST

Query Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/query
Body Params
collectionIdstringRequired

ID of the collection to query.


queryQueryRequired

Query preferences. See API Query Language for information about handling data queries.


includeReferencedItemsArray <ReferencedItemToInclude>

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.


consistentReadbooleanRequired

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.


returnTotalCountbooleanRequired

When true, the query response must include the total number of items that match the query.

Response Object
itemsArray <object>

Retrieved items.


pagingMetadataPagingMetadata

Pagination information.

Request
cURL
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 }'
Response
JSON
{ "items": [ { "name": "New York", "_id": "c285e77c-a86b-4361-a55f-c6b934d70187", "population": 8300000.0, "country": "US", "isCapital": false } ], "pagingMetadata": { "total": 1 } }
Errors
ItemAlreadyExistsobjectstatus code: 409
ItemNotFoundobjectstatus code: 404
CollectionAlreadyExistsobjectstatus code: 409
CollectionNotFoundobjectstatus code: 404
ReferenceAlreadyExistsobjectstatus code: 409
ReferenceNotFoundobjectstatus code: 404
ValidationErrorobjectstatus code: 400
CollectionChangeNotSupportedobjectstatus code: 400
BadRequestobjectstatus code: 400
Did this help?

POST

Count Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/count
Body Params
collectionIdstringRequired

ID of the collection to query.


filterstructRequired

Filter to specify which items to count. See API Query Language for more information about handling data queries.


consistentReadbooleanRequired

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.

Response Object
totalCountinteger

Number of items that match the query.

Request
cURL
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 }'
Response
JSON
{ "totalCount": 42 }
Did this help?

POST

Aggregate Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/aggregate
Body Params
collectionIdstringRequired

ID of the collection on which to run the aggregation.


initialFilterstruct

Filter to apply to the collection's data before aggregation. See API Query Language for more information about handling data queries.


aggregationAggregation

Aggregation to apply to the data.


finalFilterstruct

Filter to apply to the processed data after aggregation. See API Query Language for more information about handling data queries.


sortArray <Sorting>

Sorting configuration.


consistentReadbooleanRequired

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.


returnTotalCountbooleanRequired

When true, the query response must include the total number of items that match the query.


ONE OF:

pagingPaging

cursorPagingCursorPaging
Response Object
itemsArray <object>

Aggregation results. Each result must contain a field for each groupingFields value, and a field for each operations.resultFieldName value.


pagingMetadataPagingMetadata

Paging information.

Aggregation request with an initial filter, aggregation operations, and a final filter.

Request
cURL
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 }'
Response
JSON
{ "items": [ { "country": "US", "sumPopulation": 2000000.0, "countOfCities": 25.0 }, { "country": "CA", "sumPopulation": 1000000.0, "countOfCities": 10.0 } ], "pagingMetadata": { "total": 2 } }
Did this help?

POST

Query Distinct Values


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/query-distinct-values
Body Params
collectionIdstringRequired

ID of the collection to query.


filterstruct

Filter to apply to the collection's data before aggregation. See API Query Language for more information about handling data queries.


fieldNamestringRequired

Item field name for which to return all distinct values.


orderstring

Order to by which to sort the results. Valid values are ASC and DESC.


consistentReadbooleanRequired

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.


returnTotalCountbooleanRequired

When true, the query response must include the total number of items that match the query.


ONE OF:

pagingPaging

cursorPagingCursorPaging
Response Object
distinctValuesArray <Value>

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.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
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 }'
Response
JSON
{ "distinctValues": ["US", "CA"], "pagingMetadata": {} }
Did this help?

POST

Insert Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/insert
Body Params
collectionIdstringRequired

ID of the collection in which to insert the items.


itemsArray <object>RequiredminItems 1

Items to insert.

Response Object
resultsArray <DataItemModificationResult>

Response must include either the inserted item or an error.

Request
cURL
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" }] }'
Response
JSON
{ "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" } } } ] }
Did this help?

POST

Update Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/update
Body Params
collectionIdstringRequired

ID of the collection in which to update the items.


itemsArray <object>RequiredminItems 1

Items to update.

Response Object
resultsArray <DataItemModificationResult>

Response must include either the updated item or an error.

Request
cURL
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" }] }'
Response
JSON
{ "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" } } } ] }
Did this help?

POST

Remove Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/remove
Body Params
collectionIdstringRequired

ID of the collection from which to remove items.


itemIdsArray <string>RequiredminItems 1

IDs of items to remove.

Response Object
resultsArray <DataItemModificationResult>

Response must include either the removed item or an error.

Request
cURL
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"] }'
Response
JSON
{ "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" } } } ] }
Did this help?

POST

Truncate Data Items


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/truncate
Body Params
collectionIdstringRequired

ID of the collection from which to remove all items.

Response Object
Returns an empty object.
Truncate a given collection
Request
cURL
curl POST https://external-db.example.com/v3/items/truncate \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: <AUTH>' \ --d '{ "collectionId": "cities" }'
Response
JSON
{}
Did this help?

POST

Query Referenced Data Items


Developer Preview

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:

  • This endpoint does not retrieve the full referenced items of referenced items. For example, the referenced Actors collection might itself contain a multi-reference field with references to Award items in an Awards collection. When calling this endpoint to retrieve the refernced items of any Movie item, the response contains the referenced Actor items, but only the IDs of the Award items. To retrieve the full Award items, the user must either call this endpoint for the Actors collection, or the Query Data Items endpoint for the Awards collection.
  • This endpoint might also be called when a user calls the isReferenced endpoint of the Wix Data API.
Endpoint
POST
{DEPLOYMENT-URI}/v3/items/query-referenced
Body Params
collectionIdstringRequired

ID of the collection to query.


referringItemIdsArray <string>maxItems 1000

IDs of the referring items. If the array is empty, return results for all referring items.


referencedItemIdsArray <string>maxItems 1000

IDs of the referenced items. If the array is empty, return all referenced items for the referring items.


orderstring

Order to by which to sort the results. Valid values are ASC and DESC.


referringFieldKeystringRequired

Field ID to query in the referring collection.


consistentReadbooleanRequired

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.


fieldsToReturnArray <string>

Fields to return in the referenced item. If the array is empty or not provided, all fields in the referenced item are returned.


returnTotalCountbooleanRequired

When true, the response includes the total number of the items that match the query.


includeReferencedItemsbooleanRequired

When true, the response includes the full referenced items. When false, only the IDs of referenced items be returned.


ONE OF:

pagingPaging

Offset-based paging


cursorPagingCursorPaging

Cursor-based paging

Response Object
itemsArray <ReferencedItem>

Retrieved references.


pagingMetadataPagingMetadata

Paging information.

For a single data item, query and return a specified referenced item.

Request
cURL
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 }'
Response
JSON
{ "items": [ { "referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187", "referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284" } ], "pagingMetadata": {} }
Did this help?

POST

Insert Data Item References


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/insert-references
Body Params
collectionIdstringRequired

ID of the referring collection.


referringFieldKeystringRequired

Field ID of the field in the referring collection to insert references into.


referencesArray <ReferenceId>RequiredminItems 1

References to insert.

Response Object
resultsArray <ReferenceModificationResult>

Response must include either the inserted reference or an error.

Creates a reference from one item to another.

Request
cURL
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" }] }'
Response
JSON
{ "results": [ { "reference": { "referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187", "referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284" } } ] }
Did this help?

POST

Remove Data Item References


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/remove-references
Body Params
collectionIdstringRequired

ID of the referring collection.


referringFieldKeystringRequired

Field ID of the field in the referring collection to remove references from.


referencesArray <ReferenceId>RequiredminItems 1

References to remove.

Response Object
resultsArray <ReferenceModificationResult>

Response must include either the removed reference or an error.

Request
cURL
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" }] }'
Response
JSON
{ "results": [ { "reference": { "referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187", "referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284" } } ] }
Did this help?

POST

List Collections


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/collections/get
Body Params
collectionIdsArray <string>

IDs of collections to retrieve. If empty, all available collections are retrieved.

Response Object
collectionsArray <Collection>

List of the retrieved collections.

Request
cURL
curl POST https://external-db.example.com/v3/collections/get \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: <AUTH>' \ --d '{ "collectionIds": [] }'
Response
JSON
{ "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" } ] }
Did this help?

POST

Create Collection


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/collections/create
Body Params
collectionCollection

Details of the collection to create.

Response Object
collectionCollection

Details of the created collection.

Create a collection
Request
cURL
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" } }'
Response
JSON
{ "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" } }
Did this help?

POST

Update Collection


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/collections/update
Body Params
collectionCollection

Updated structure details for the specified collection.

Response Object
collectionCollection

Updated collection details.

Update a collection
Request
cURL
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" } }'
Response
JSON
{ "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" } }
Did this help?

POST

Delete Collection


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/collections/delete
Body Params
collectionIdstringRequired

ID of the collection to delete.

Response Object
Returns an empty object.
Delete a collection
Request
cURL
curl POST https://external-db.example.com/v3/collections/delete \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: <AUTH>' \ --d '{ "collectionId": "cities" }'
Response
JSON
{}
Did this help?

POST

Get Capabilities


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/capabilities/get
Request
This endpoint does not take any parameters.
Response Object
supportsCollectionModificationsboolean

Whether the external database supports creating new collections, updating the structure of existing collections, or deleting them.


supportedFieldTypesArray <string>

Field types the external database supports. This field only applies when supportsCollectionModifications is true.

Get the capabilities of the specified collection
Request
cURL
curl POST https://external-db.example.com/v3/capabilities/get \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: <AUTH>' \ --d '{ }'
Response
JSON
{ "supportsCollectionModifications": true, "supportedFieldTypes": ["TEXT", "DATETIME", "NUMBER", "BOOLEAN"] }
Did this help?