Step-by-Step Guide on How to Use External Database Collections for Better Wix Website Performance

Integrate your external databases into your Wix sites. . Learn more (Additional information about this section) Guides Introduction Authentication Errors Example Data Provisioning ARTICLE Provisioning Overview POST : Setup initial connectivity between your adapter and the wix-data backend. Provision Request Context OBJECT : The Request Context object is sent with every request. It contains information about who made the request, and which site and which external collection ... Request Context Object Schema ARTICLE Schema Overview OBJECT : Metadata describing collection or table. Schema Object POST : Get a list of schema objects base on a list of schema IDs. Find Schemas POST : Get a list of all schema objects. List Available Schemas Data ARTICLE Data Overview POST : Insert a new item into a collection. Insert Item POST : Get an item based on its itemId. Get Item POST : Get a list of items based on a filter. Find Items POST : Update an item in a collection. Update Item POST : Remove an item from a collection. Remove Item POST : Count the number of items that match a filter. Count Introduction Integrate your external database into your Wix site using external collections and building an external database collection adapter. The External Database Collections SPI describes the API requests your adapter needs to expect from your Wix site, and the responses your Wix site expects in return. The SPI takes the request from your Wix site and converts it into a request that your external database can receive. It also takes the response from the external database and converts it into a JSON response that your Wix site can receive. You can learn more about working with External Databases on your Wix site . here Mandatory Endpoints The following endpoints are mandatory and must be implemented in your adapter. All other endpoints are optional. The implemented endpoints must be exposed via the in the list. schema object allowedOperations For example: : { : , : , : [ , , , , , ], : , : , : { } } "schema" "displayName" "myCollection" "id" "myCollection" "allowedOperations" "get" "find" "count" "update" "insert" "remove" "maxPageSize" 50 "ttl" 3600 "fields" "..." Data Structures _id Each table or collection must contain an column or attribute of type string.If you create new data outside of your Wix site, or you are importing new data for use with your site, you must populate this field with a unique value. If you create new data in your site, the Wix Data backend will generate a unique 36-character UUID for each item created.The attribute can be any length but if items are created by your Wix site, it must be at least 36 characters long. _id _id _owner (optional) For data created by your Wix site, Wix Data backend will populate the attribute with a 36-character UUID identifying the user who created the data. If the visitor is not a logged-in member, the attribute is based on a browser cookie and is therefore consistent between sessions. The attribute will be null if the new data was created by a backend process. _owner _owner _owner Dates All dates must be an string encapsulated in an object. For example: "myDate" :{“$date”:”2001-02-11T00:00:00.000Z”} ISO Authentication The External Database Collections SPI uses the to manage authentication and authorization. HTTP authentication is not implemented. The object within the request context object can contain a key for authentication purposes. In the prototype and examples, the property is used. This key is configured in the Wix Editor when and sent by the Wix Data backend in every request. request context object settings secretKey adding the external collection In addition to the settings object, the request context object contains the , , , and . Each of these properties can be used to implement a permissions model controlling access to operations and data. Permissions can be implemented based on the site making the request, the external collection within the site, the visitor's member ID, and the member's role. instanceId installationId memberId memberRole Errors Each SPI call returns a response including an HTTP status code. If an error response is required, the response must include an error status code and a message that describes the type of error that occurred. The error message should be in the following format: { : } "message" "..." Use the following HTTP Status/Error codes: Note 4XX statuses will appear in the error produced by the Wix Data function call. Example Data The examples in this reference are based on the prototype deployed to Google AppEngine. Adapter for MySQL databases The prototype is connected to a database with the following tables and data: Car Table Car Table Data Manufacturer Table Manufacturer Table Data Provisioning Overview The Provision SPI describes the endpoint and payload for provisioning API requests to your external database and the payload for their success and failure responses. Provision API requests occur when you initially connect your endpoint to your site or change its settings. A response status of anything other than a 200 status will result in the configuration of the not being saved by the Wix Editor. external collection Provision Setup initial connectivity between your adapter and the wix-data backend. https://example.com/provision POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 401 - Not authorized. 400 - Request not valid. Returns an empty object. Provisioning request. curl -X POST \ --header \ --data-raw 'https://mysql-adaptor.com/provision' 'Content-Type: application/json' '{ "requestContext": { "settings": { "secretKey": "myBigSecret" }, "installationId": "987fe654-3d21-4def-ab5c-6d78e90f123a", } }' {} Request Context Object The Request Context object is sent with every request. It contains information about who made the request, and which site and which external collection configuration made the request. Use the in the request context object to implement permissions in your adapter. member_id Settings The contents of the object are static and set in the Configuration section when . Use the settings object to carry any static data you want to send to the adapter from your site. The prototype adaptor uses the settings object to receive the for authentication. Add attributes to the settings object to support any functionality you want to implement in your adapter. settings setting up the external collection secretKey instance_id The is a UUID that uniquely identifies the Wix site that is making the request. You can create an external database collection in more than one Wix site that points to the same adaptor and external database. Use the instance_id to control access to your date on a per-site basis. instance_id installation_id The is a UUID that uniquely identifies the external collection configuration within your site. You can create more than one external collection in the same site that points to the same adaptor and external database. Each of these external collections will be identified by its own UUID, allowing you to implement different functionality and permissions for each one. installation_id member_id The identifies the site visitor making the request. When creating new items, the Wix data backend populates the attribute with the member_id. If the visitor is not a logged-in member, the member_id is based on a browser cookie and therefore consistent between sessions. The member_id will be null if the code that made the request was triggered by a backend process. Use member_id to filter data by user and to implement permissions in your adapter. member_id _owner member_role The describes the role of the site visitor making the request. If the request is made by backend code and the function uses the option, the will be set to and the will be . In all other cases where backend code makes the request, the will be set to and the will be . member_role find() suppressAuth member_role BACKEND_CODE member_id null member_role VISITOR member_id null Attributes https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Request Context Example request context object. { : { : { : }, : , : , : , : }} "requestContext" "settings" "secretKey" "mySecureSecret" "instanceId" "12a345b6-7890-98d7-65e4-f321abc1de23" "installationId" "987fe654-3d21-4def-ab5c-6d78e90f123a" "memberId" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "role" "OWNER" Schema Overview The Schema SPI describes the endpoints and payloads for schema API requests to your external database and the payloads for their success and failure responses. Schema API requests may occur whenever your site needs to interact with the data in your external collection. The schema may be cached for at most the amount of time indicated in the field of the object. ttl schema Schema Object Metadata describing collection or table. Attributes Schema Example schema object. { : { : , : , : [ , , , , , ], : , : , : { : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] } } }} "schema" "displayName" "manufacturer" "id" "manufacturer" "allowedOperations" "get" "find" "count" "update" "insert" "remove" "maxPageSize" 50 "ttl" 3600 "fields" "name" "displayName" "name" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "country" "displayName" "country" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "established" "displayName" "established" "type" "datetime" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_id" "displayName" "_id" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_owner" "displayName" "_owner" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "share_price" "displayName" "share_price" "type" "number" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" Find Schemas Get a list of schema objects base on a list of schema IDs. https://example.com/schemas/find POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 404 - No schemas found Get a list of schema objects in the list ["car","manufacturer"]. curl -X POST \ ://mysql-adapter.com/schemas/find' \ : { : { : }, : , : , : , : }, : [ , ] }' 'https --header 'Content-Type: application/json' \ --data-raw '{ "requestContext" "settings" "secretKey" "mySecureSecret" "instanceId" "12a345b6-7890-98d7-65e4-f321abc1de23" "installationId" "987fe654-3d21-4def-ab5c-6d78e90f123a" "memberId" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "role" "OWNER" "schemaIds" "car" "manufacturer" { : [ { : , : , : [ , , , , , ], : , : , : { : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] } } }, { : , : , : [ , , , , , ], : , : , : { : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] } } } ]} "schemas" "displayName" "car" "id" "car" "allowedOperations" "get" "find" "count" "update" "insert" "remove" "maxPageSize" 50 "ttl" 3600 "fields" "_id" "displayName" "_id" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_owner" "displayName" "_owner" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "make" "displayName" "make" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "model" "displayName" "model" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "year" "displayName" "year" "type" "number" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "date_added" "displayName" "date_added" "type" "datetime" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "displayName" "manufacturer" "id" "manufacturer" "allowedOperations" "get" "find" "count" "update" "insert" "remove" "maxPageSize" 50 "ttl" 3600 "fields" "name" "displayName" "name" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "country" "displayName" "country" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "established" "displayName" "established" "type" "datetime" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_id" "displayName" "_id" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_owner" "displayName" "_owner" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "share_price" "displayName" "share_price" "type" "number" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" List Available Schemas Get a list of all schema objects. https://example.com/schemas/list POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Get a list of all available schemas. curl -X POST ://mysql-adapter.com/schemas/list' \ : { : { : }, : , : , : , : } }' 'https --header 'Content-Type: application/json' \ --data-raw '{ "requestContext" "settings" "secretKey" "mySecureSecret" "instanceId" "12a345b6-7890-98d7-65e4-f321abc1de23" "installationId" "987fe654-3d21-4def-ab5c-6d78e90f123a" "memberId" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "role" "OWNER" { : [ { : , : , : [ , , , , , ], : , : , : { : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] } } }, { : , : , : [ , , , , , ], : , : , : { : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] }, : { : , : , : [ , , , , , , , , , , , ] } } } ]} "schemas" "displayName" "car" "id" "car" "allowedOperations" "get" "find" "count" "update" "insert" "remove" "maxPageSize" 50 "ttl" 3600 "fields" "_id" "displayName" "_id" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_owner" "displayName" "_owner" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "make" "displayName" "make" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "model" "displayName" "model" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "year" "displayName" "year" "type" "number" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "date_added" "displayName" "date_added" "type" "datetime" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "displayName" "manufacturer" "id" "manufacturer" "allowedOperations" "get" "find" "count" "update" "insert" "remove" "maxPageSize" 50 "ttl" 3600 "fields" "name" "displayName" "name" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "country" "displayName" "country" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "established" "displayName" "established" "type" "datetime" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_id" "displayName" "_id" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "_owner" "displayName" "_owner" "type" "text" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" "share_price" "displayName" "share_price" "type" "number" "queryOperators" "eq" "lt" "gt" "hasSome" "and" "lte" "gte" "or" "not" "ne" "startsWith" "endsWith" Data Overview The Data SPI describes the endpoints and payloads for data API requests to your external database and the payloads for their success and failure responses. Data API requests occur whenever your site needs to interact with the data in your external collection. Insert Item Insert a new item into a collection. https://example.com/data/insert POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 400 - Invalid item, Constraint violation. 409 - Item already exists. Insert an item into a collection. curl -X POST 'https://mysql-adapter.com/data/ - : application/ { : { : { : }, : , : , : , : }, : , : { : , : , : , : , : , : { : } } } insert ' \ --header ' Content Type json ' \ --data-raw ' "requestContext" "settings" "secretKey" "mySecureSecret" "instanceId" "12a345b6-7890-98d7-65e4-f321abc1de23" "installationId" "987fe654-3d21-4def-ab5c-6d78e90f123a" "memberId" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "role" "OWNER" "collectionName" "car" "item" "_id" "12345678-abcd-9876-fedc-a9876543210" "_owner" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "make" "BMW" "model" "i8" "year" 2020 "date_added" "$date" "2020-01-01T21:00:00.000Z" ' { : { : , : , : , : , : , : { : } }} "item" "_id" "12345678-abcd-9876-fedc-a9876543210" "_owner" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "make" "BMW" "model" "i8" "year" 2020 "date_added" "$date" "2020-01-01T21:00:00.000Z" Get Item Get an item based on its . itemId https://example.com/data/get POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 404 - Item not found. Get an item from a collection based on the field. _id curl -X POST \ --header \ --data-raw 'https://mysql-adapter.com/data/get' 'Content-Type: application/json' '{ "requestContext": { "settings": { "secretKey": "mySecureSecret" }, "instanceId": "12a345b6-7890-98d7-65e4-f321abc1de23", "installationId": "987fe654-3d21-4def-ab5c-6d78e90f123a", "memberId": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77", "role": "OWNER" }, "collectionName": "car", "itemId": "86cbf595-d369-48bb-8649-c6c082c003ca" }' { : { : , : , : , : , : , : { : } }} "item" "_id" "86cbf595-d369-48bb-8649-c6c082c003ca" "_owner" "81c9168e-95b8-47fd-8e6a-ad9fdf71b38e" "make" "Ford" "model" "Mustang" "year" 2001 "date_added" "$date" "2001-06-07T21:00:00.000Z" Find Items Get a list of items based on a filter. https://example.com/data/find POST: Body Params Response Object Get data matching a filter from a collection. curl -X POST \ --header \ --data-raw 'https://mysql-adapter.com/data/find' 'Content-Type: application/json' '{ "requestContext": { "settings": { "secretKey": "mySecureSecret" }, "instanceId": "12a345b6-7890-98d7-65e4-f321abc1de23", "installationId": "987fe654-3d21-4def-ab5c-6d78e90f123a", "memberId": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77", "role": "OWNER" }, "collectionName": "car", "filter": { "operator": "$and", "value": [ { "operator": "$contains", "fieldName": "make", "value": "a" }, { "operator": "$gt", "fieldName": "year", "value": 2018 } ] }, "sort": [ { "fieldName": "year", "direction": "asc" } ], "skip": 0, "limit": 10000 }' { : [ { : , : , : , : , : , : { : } }, { : , : , : , : , : , : { : } } ], : } "items" "_id" "95953ca3-5fe5-4ce7-9cca-9bcc1ba64ba6" "_owner" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "make" "Toyota" "model" "Corolla" "year" 2019 "date_added" "$date" "2020-09-30T21:30:00.000Z" "_id" "20cd8f8d-1a0f-4530-91df-6d31fe9e83a5" "_owner" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "make" "Ferrari" "model" "812GTS" "year" 2020 "date_added" "$date" "2020-03-31T21:00:00.000Z" "totalCount" 2 Update Item Update an item in a collection. https://example.com/data/update POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 400 - Invalid item, Constraint violation. 404 - Item not found Update an item in a collection. curl -X POST \ --header \ --data-raw 'https://mysql-adapter.com/data/update' 'Content-Type: application/json' '{ "requestContext": { "settings": { "secretKey": "mySecureSecret" }, "instanceId": "12a345b6-7890-98d7-65e4-f321abc1de23", "installationId": "987fe654-3d21-4def-ab5c-6d78e90f123a", "memberId": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77", "role": "OWNER" }, "collectionName": "car", "item": { "_id": "86cbf595-d369-48bb-8649-c6c082c003ca", "_owner": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77", "model": "Mustang GTR" } }' { : { : , : , : }} "item" "_id" "86cbf595-d369-48bb-8649-c6c082c003ca" "_owner" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "model" "Mustang GTR" Remove Item Remove an item from a collection. https://example.com/data/remove POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 404 - Item not found Delete an item from a collection. curl --X POST \ --header \ --data-raw 'https://mysql-adapter.com/data/remove' 'Content-Type: application/json' '{ "requestContext": { "settings": { "secretKey": "mySecureSecret" }, "instanceId": "12a345b6-7890-98d7-65e4-f321abc1de23", "installationId": "987fe654-3d21-4def-ab5c-6d78e90f123a", "memberId": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77", "role": "OWNER" "collectionName": "car", "itemId": "12345678-abcd-9876-fedc-a9876543210" }' { : { : , : , : , : , : , : { : } }} "item" "_id" "12345678-abcd-9876-fedc-a9876543210" "_owner" "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77" "make" "BMW" "model" "i8" "year" 2020 "date_added" "$date" "2020-01-01T21:00:00.000Z" Count Count the number of items that match a filter. https://example.com/data/count POST: Body Params https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection Response Object Status/Error Codes: 400 - Invalid query. Count items in a collection that match a filter. curl -X POST \ --header \ --data-raw 'https://mysql-adapter.com/data/count' 'Content-Type: application/json' '{ "requestContext": { "settings": { "secretKey": "mySecureSecret" }, "instanceId": "12a345b6-7890-98d7-65e4-f321abc1de23", "installationId": "987fe654-3d21-4def-ab5c-6d78e90f123a", "memberId": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77", "role": "OWNER" }, "collectionName": "car", "filter": { "operator": "$contains", "fieldName": "make", "value": "Hyundai" } }' { : } "totalCount" 2 Previously published at https://www.wix.com/velo/reference/spis/external-database-collections/external-database-collections/data/count