[wp-trac] [WordPress Trac] #38900: Customize: Add REST API endpoints for changesets

[WordPress Trac]

#38900: Customize: Add REST API endpoints for changesets
-----------------------------+---------------------------
 Reporter:  westonruter      |       Owner:  valendesigns
     Type:  feature request  |      Status:  assigned
 Priority:  normal           |   Milestone:  4.8
Component:  Customize        |     Version:
 Severity:  normal           |  Resolution:
 Keywords:  needs-patch      |     Focuses:  rest-api
-----------------------------+---------------------------

Old description:

> In WordPress 4.7, the `customize_changeset` post type was introduce to
> persistently store the `customized` state until the staged changes are
> published (see #30937). In 4.7 the changesets were managed using the same
> `customzie_save` Admin Ajax request that has always been used to send
> customizer changes to WordPress. However, changesets are designed so that
> they needn't be used in the current “Customizer” app at all. A
> `customize_changeset` post can be created by any means (such as via WP-
> CLI) and as long as the HTTP request includes the
> `customize_changeset_uuid` query parameter, the changes stored within the
> changeset will be applied to preview in the response. As such, changesets
> for headless sites and apps consuming the REST API to also make use of
> WordPress's framework for previewing changes.
>
> In addition to an app being able to preview changes in read requests to
> the REST API, changesets must also be able to be written via the REST
> API. This is also relevant to creating new changesets for previewing
> changes on a site's frontend (frontend editing).
>
> The Customize Snapshots has some initial read-only endpoints for the REST
> API: https://github.com/xwp/wp-customize-snapshots/pull/63
> It did not yet implement support for writing changes:
> https://github.com/xwp/wp-customize-snapshots/issues/64
>
> A few points about what how the changeset endpoints could behave:
>
> - Allow changesets posts to be created and updated, ensuring that
> `content` is in the proper format as an object mapping setting IDs to
> setting params. The `content` could be the decoded contents of the
> `post_content`.
> - Prevent editing of `slug`, since the UUID should never change.
> - Allow making changes to the `content` via `PATCH` method updates.
> - Use the UUID (`post_name`) of the `customize_changeset` posts as the
> resource IDs as opposed to the underlying post ID. We really don't need
> regular post IDs since snapshots have UUIDs. Really a random `PUT`
> request could be made to create a snapshot if it just supplies a proper
> UUID.
> - Let the endpoint be `/changesets` as opposed to `/customize-
> changesets`.
>
> Ideally the `customize_save` Ajax requests initiated by
> `wp.customize.previewer.save()` and
> `wp.customize.requestChangesetUpdate()` could both make use of the
> changesets endpoints, replacing the use of the `customize_save` Admin
> Ajax request.
>
> Updates to a changeset should be invoking
> `WP_Customize_Manager::save_changeset_post()` to apply the changes to the
> post.

New description:

 In WordPress 4.7, the `customize_changeset` post type was introduce to
 persistently store the `customized` state until the staged changes are
 published (see #30937). In 4.7 the changesets were managed using the same
 `customzie_save` Admin Ajax request that has always been used to send
 customizer changes to WordPress. However, changesets are designed so that
 they needn't be used in the current “Customizer” app at all. A
 `customize_changeset` post can be created by any means (such as via WP-
 CLI) and as long as the HTTP request includes the
 `customize_changeset_uuid` query parameter, the changes stored within the
 changeset will be applied to preview in the response. As such, changesets
 for headless sites and apps consuming the REST API to also make use of
 WordPress's framework for previewing changes.

 In addition to an app being able to preview changes in read requests to
 the REST API, changesets must also be able to be written via the REST API.
 This is also relevant to creating new changesets for previewing changes on
 a site's frontend (frontend editing).

 The Customize Snapshots has some initial read-only endpoints for the REST
 API: https://github.com/xwp/wp-customize-snapshots/pull/63
 It did not yet implement support for writing changes:
 https://github.com/xwp/wp-customize-snapshots/issues/64

 A few points about what how the changeset endpoints could behave:

 - Allow changesets posts to be created and updated, ensuring that
 `content` is in the proper format as an object mapping setting IDs to
 setting params. The `content` could be the decoded contents of the
 `post_content`.
 - Prevent editing of `slug`, since the UUID should never change.
 - Allow making changes to the `content` via `PATCH` method updates.
 - Use the UUID (`post_name`) of the `customize_changeset` posts as the
 resource IDs as opposed to the underlying post ID. We really don't need
 regular post IDs since snapshots have UUIDs. Really a random `PUT` request
 could be made to create a snapshot if it just supplies a proper UUID.
 - Let the endpoint be `/changesets` as opposed to `/customize-changesets`.

 Ideally the `customize_save` Ajax requests initiated by
 `wp.customize.previewer.save()` and
 `wp.customize.requestChangesetUpdate()` could both make use of the
 changesets endpoints, replacing the use of the `customize_save` Admin Ajax
 request.

 Updates to a changeset should be invoking
 `WP_Customize_Manager::save_changeset_post()` to apply the changes to the
 post.

 Feature plugin repo: https://github.com/WP-API/wp-api-customize-endpoints

--

Comment (by westonruter):

 Feature plugin repo: https://github.com/WP-API/wp-api-customize-endpoints

--
Ticket URL: <https://core.trac.wordpress.org/ticket/38900#comment:5>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform