About the External Database Connections API

The External Database Connections API enables you to connect an external database to the Wix site on which your app is installed.

Internal vs. external databases

Wix provides a comprehensive full-stack platform with integrated database capabilities. Your app can use the Data Collections API to create, modify, and delete data collections in a Wix site on which it is installed. The app can then use the Data Items API to access and manage data within those collections.

Wix's database capabilities cover a wide range of use cases for apps that need to store data. However, certain projects have very specific requirements that make it necessary to use an external database. For example, you may need to access existing data that is already stored on an external service, or you may need your data to be stored in a relational database.

Once the connection between an external database and a Wix site is established, your app can access the collection using Wix Data APIs, including the Data Items API, in the same way you would with a native collection. The owner of the Wix site on which your app is installed can also access the collection through the Content Management System(CMS) and with Velo, use the collection to create dynamic pages, and connect the collection to user input elements.

For more information on connecting external databases with a Wix site, see Integrating External Databases with Your Wix Site.

Preparing an external database

Before the External Database Connections API can connect a Wix site with an external database, you need to prepare the external database by creating an external database adaptor.

An external database adaptor is a server that translates Wix data requests from a Wix site or app into an external database's protocol, and translates the response back into a format that Wix APIs can read. This enables Wix APIs, apps, and sites to treat the external database exactly as if it was an internal data collection.

If your database is hosted on one of the major cloud platforms, you can consult one of our tutorials for instructions on how to deploy an external database adaptor.

Otherwise, for details on the required specifications for an external database adaptor, see the External Database Collections SPI.

Ensuring read-write access

If you want to enable read-write access to your external database using the Data Items API, ensure your external database's table or schema includes the following fields:

  • _id
  • _createdDate
  • _updatedDate
  • _owner If these fields are absent, access to the external database is read-only. You may prefer this option for data that your app only needs to retrieve and doesn't need to manage.

Supported databases

The External Database Connections API works with several kinds of databases. For a full list, see Supported Databases.

Was this helpful?
Yes
No

External Database Connection Object

An external database connection defines a connection between an external database and a Wix site or project.

Attributes
namestringminLength 1maxLength 255
Name of the external database connection. An external database connection may connect to one or more external data collections or tables. These are represented as connectionName/dataCollectionId.

endpointstringformat WEB_URL
Base URL for provisioning and managing data in the external database. For example: https://example.com/my-external-database.

configurationstruct
Settings passed to the external database connection as part of each request. These settings can relate to authentication, tenancy, or provide any other information needed for processing a request. Their content and structure depend on the specific requirements of the external database's API.

connectionStatusobjectRead-only
Status of the external database connection. Includes whether the connection was established successfully, and if not, the reason for the failure.

capabilitiesobjectRead-only
The external database's capabilities.
Was this helpful?
Yes
No

GetGet External Database Connection

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 an external database connection by name.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage External Database Connections
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/wix-data/v1/external-database-connections/{name}

Was this helpful?
Yes
No

DeleteDelete External Database Connection

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 an external database connection.

Note: Once an external database connection is deleted, it can't be restored. To reconnect the database you need to create a new external database connection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage External Database Connections
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/wix-data/v1/external-database-connections/{name}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetList External Database Connections

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 all external database collections associated with the site or project.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage External Database Connections
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/wix-data/v1/external-database-connections

Was this helpful?
Yes
No

PostCreate External Database Connection

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 external database connection.

The request body must include a name, an endpoint, and configuration details for the external database within the externalDatabaseConnection body parameter. If any of these are missing, the external database connection isn't created.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage External Database Connections
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/wix-data/v1/external-database-connections

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PutUpdate External Database Connection

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 an external database connection.

An external database collection name must be submitted as a path parameter. If an existing external database connection is found with the same name, that connection's details are updated. If no external database connection has that name, the request fails.

Note: After an external database connection is updated, it only contains the values provided in the request. All previous values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage External Database Connections
Learn more about permission scopes.
Endpoint
PUT
https://www.wixapis.com/wix-data/v1/external-database-connections/{externalDatabaseConnection.name}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

External Database Connection Created

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an external database connection is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.data.v1.external_database_connection.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

External Database Connection Updated

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an external database connection is updated.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.data.v1.external_database_connection.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

External Database Connection Deleted

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an external database connection is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.data.v1.external_database_connection.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No