About the Data Collections API

The Data Collections API manages the structure of CMS collections on a site. A collection defines the fields, data types, item permissions, and plugins for its data items.

With the Data Collections API, you can:

• Create collections and retrieve their definitions.
• Replace a collection definition or update selected collection and field properties.
• Configure plugins for publishing, dynamic page URLs, multilingual content, and CMS display settings.
• Delete collections and restore recently deleted collections.

Use the Data Items API to store and retrieve the items in these collections.

Data collections and their structure

Wix sites store data in collections. A collection determines the structure of the data to be stored, defining the fields each item contains, and the data type of each field. Wix users can create and modify collections for their site using the Content Management System (CMS).

With the Data Collections API, you can use code to create, modify, and delete collections in a Wix site. You can then store and retrieve data in these collections using the Data Items API.

Permissions

Access to a data collection is controlled by its permissions. These permissions are defined in the collection object and they specify which types of user can perform actions on the items contained in the collection.

Wix Data recognizes 4 roles:

• ADMIN: The site owner.
• SITE_MEMBER_AUTHOR: A signed-in user who has added content to the collection.
• SITE_MEMBER: Any signed-in user.
• ANYONE: Any site visitor.

For each of the 4 basic actions (inserting, updating, removing, and reading content) the minimal role required must be set. For example, if you want to allow only site members to read items, and only the site owner to insert, update, and remove items, set the collection permissions as follows:

• insert: ADMIN
• update: ADMIN
• remove: ADMIN
• read: SITE_MEMBER

Update collection and field definitions

Use Patch Data Collection or Patch Data Collection Field to change selected properties while preserving the others. The field mask identifies which supported properties to change. When omitted in a REST request, the mask is inferred from the supplied object.

Update Data Collection replaces the collection definition. Update Data Collection Field replaces one field's definition while retaining other fields. Include every writable property you need to preserve when using these methods.

Before you begin

It's important to note the following points before starting to code:

• Wix Data APIs require the site's code editor to be enabled. For an app, add a data collections extension to enable it automatically and create collections when the app is installed.
• Collection capabilities determine which collection and item operations are supported. App-managed and external collections can support different operations from user-created collections.
• Calls to retrieve a collection or bulk-retrieve collections with a visitor identity return a limited view. Don't rely on these calls to retrieve item permissions or index limits.

Use cases

• Set up a tutorials collection with references to categories and authors.
• Add draft/publish functionality to a collection.
• Rename a collection field without changing its other properties.

Terminology

• Collection definition: The fields, data types, permissions, and plugins that describe a collection.
• Reference field: A field that links an item to an item in another collection. A multi-reference field links to multiple items.
• Collection plugin: Configuration that extends a collection's behavior, such as publication status or URL generation.