About the App Extensions API

The Extensions API lets you create and manage the components of an app while building or updating the app. A component is a versioned building block of an app, such as a page, a widget, or a webhook. Extensions let you provide users with the right data for the app version they have installed.

In Wix app documentation and the App Dashboard, components are referred to as extensions. In this API, the same concept is called a component. When you create or update a component with this API, you're configuring an app extension such as a page, widget, or webhook.

With the App Extensions API, you can:

• Create, update, and delete components.
• Validate component configuration before saving changes.
• Restore deleted draft components.
• Retrieve an app's draft components, or a component by ID or external ID.
• Query components and retrieve the latest component versions while preparing an app version.

How components work

Components are immutable and versioned. Every change to a component creates a new version, and component versions are never deleted. Component changes are saved on the app draft until you release them as part of an app version. When an app version is promoted to production, it includes the latest version of each of the app's non-deleted components.

The draft version of a component is version 0. Deleting a component removes only its draft version. Previously published versions remain. You can restore a deleted draft component, then call Get Component or Get Draft App Components to retrieve the restored component state.

Each component has a type, such as a page or a widget. Component types are defined centrally by Wix, and a type's owner can enforce validations:

• Singular: only one component of that type can exist per app.
• Non-updatable: the component's data can't be changed.
• Non-deletable: the component can't be deleted.

A component type can also define custom validation and enrichment that run when a component is created or updated.

The type field determines the structure of the component's data. type uses the ComponentType enum, and data uses the matching ComponentData oneof variant. The oneof variant name matches the enum value in lower case. For example, a WIDGET component uses the widget data variant. Use component catalog display metadata, exampleComponentData, and the type's learn-more link when preparing a type-specific component payload.

Before you begin

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

• Every component belongs to an app. Provide the appId in component requests, and include appId as a filter when querying components.
• externalId is a developer-provided lookup key scoped to an app. It isn't required to be unique, and Get Components By External ID returns all matching components for the app.
• Use this API to manage components before releasing them as part of an app version. After release, consume the app's component data through the read-optimized runtime APIs available for released app versions.

Use cases

• Add components to an app

Terminology

• Extension: Product-facing term for a component in Wix app documentation and the App Dashboard.
• Component: A versioned building block of an app, such as a page, widget, or webhook.
• Component type: The kind of a component, such as a page or widget. Defined centrally by Wix.
• Draft version: The mutable, in-progress version of a component (version 0).
• Version: An immutable snapshot of a component. A new version is created on each change.