Now Available on All Stores: Page Widgets APIs

Katie Hoesley

We’re thrilled to announce the launch of a new set of APIs: Page Widgets APIs. This new set of APIs help achieve parity with the Page Builder Control Panel user interface by allowing developers to create, modify and view layouts via API and are available on all stores.  

This API contains two key endpoints: 

  1. A new endpoint - Get a Page Snapshot - that allows a developer to retrieve a “snapshot” of a page’s Page Builder content - including regions, layouts, widgets that belong to each region and the individual configurations themselves)

  2. A new endpoint - Overwrite a Page - that allows a developer to modify/overwrite Page Builder content on a particular page programmatically

The Page Widgets API retrieves a snapshot of all widget content on the page, which could include multiple layouts and content across multiple regions. The API also accepts a post request, as mentioned previously, that has the entire page's content defined. Post requests to this API endpoint overwrite the entire page's content each time with the body content of the request - so developers cannot modify or add a single layout in isolation from the rest of the page, but rather grab or overwrite the entire collection. 

Previously, layouts could only be created in the Page Builder Control PaneI. The Page Widgets API solves this problem by exposing the layouts in the API. However, this is not an endpoint to directly create, update, or edit a layout in isolation. Rather, it exposes the layout object within the larger page snapshot context. When I use the API I would get the entire page returned to me - like this example below:

page-widgets-1

A widget can also be a direct descendant of the region itself - so via this API, you can still place a widget directly into a region and are not required to nest a widget within a layout. 

Developers can’t dig in and directly edit, for example, Widget 4. In order to update Widget 4, you’d need to send a post request that updates the entire page. To update Widget 4 to Widget 4.5, for example, your request would look like this: 

page-widgets-2

If, for example, you submitted a post request like below, it would overwrite the entire page and then only have that content available, deleting everything previously there.  

page-widgets-3

What does the Page Widgets API do?

Until now, the only way for developers to create a layout was through the Page Builder control panel, where you can drag and drop layouts into regions. There was no option, until now, to make layout changes via API. 

The Page Widgets API makes pages layouts portable by exposing and allowing the layout configurations, dropzones, and widgets to be retrieved or updated within the context of the entire page snapshot.

The image below outlines the properties and relationships of the corresponding Page Widget objects.

page-widget

Use cases 

This API supports (including but not limited to)::

  • Retrieving a snapshot of a specified page that includes all the regions on the page, the layouts and widgets that belong to each region, the widgets that are nested within a layout, and the configuration of the layout and widgets.

  • Migrating the snapshot to another store and retaining region placement, layout configuration and widget configurations.

  • Using the snapshot as a form of version control and restore content within the same existing store if it is accidentally deleted

  • Using the snapshot of a page to quickly duplicate pages that require the same layout template

  • Transforming a non-BigCommerce site into layouts and widgets and migrate this content to a BigCommerce store

Best Practices for Migrating Content Between Stores

  • Ensure that prior to migration both the source store and the target store have the same themes uploaded that contain the same regions. You can use the Get Themes Region endpoint to ensure that the source page and the target page have the same regions

  • Both stores should contain the same custom widget templates. 

  • To migrate platform widgets, we recommend using the widget kind to find the corresponding widget template UUID. The kind attribute for platform widgets are read-only so this will always successfully return the correct UUID

  • To migrate custom widgets, you can use the name attribute to find the corresponding widget template UUID but we recommend matching using the template attribute.

  • If there is store-specific data such as Product ID in the widget configuration and the storefront_query_params they will need to be replaced by the corresponding identifiers in the target store. 

How do I get started with the Page Widgets API? 

All you need to do before you get started is make sure you have a store-level or app-level API account with OAuth scopes that include “modify” permissions for Content, so you’re able to view and modify store content using the API. 

Once you have that, you’re ready to go! 

For more information, visit our Developer Documentation and API Reference on Page Widgets. 

Still have questions? Email our DevRel team, tweet at us, or comment on this article!