[wp-trac] [WordPress Trac] #40510: REST API: Post Revisions: Adding support for pagination

[WordPress Trac]

#40510: REST API: Post Revisions: Adding support for pagination
----------------------------------------+-----------------------
 Reporter:  benoitperson                |       Owner:  flixos90
     Type:  enhancement                 |      Status:  assigned
 Priority:  normal                      |   Milestone:  5.0
Component:  REST API                    |     Version:  4.7
 Severity:  normal                      |  Resolution:
 Keywords:  has-patch needs-unit-tests  |     Focuses:  rest-api
----------------------------------------+-----------------------
Changes (by flixos90):

 * keywords:  needs-patch => has-patch needs-unit-tests
 * owner:   => flixos90
 * status:  new => assigned
 * milestone:  Future Release => 5.0


Old description:

> The post revisions REST endpoint currently has no support for pagination.
> While it works well for most usages with fairly low counts of revisions
> (Wordpress.com limits the number at 25 for instance), on posts with a
> revision count in the hundreds (or even thousands), this can quickly
> yield unreasonably large (Mb+ of pure text) and long (several seconds on
> my "test" instances) responses.
>
> The API already supports pagination for a vast majority of ressources
> (posts, pages, categories, tags, users) and is normalised around using 2
> integer parameters: `page` (default: `1`)and `per_page` (default: `10`).
>
> I wonder if there is any reason why pagination was never implemented on
> that endpoint? Is it something potentially worth working on? Considering
> some of the past issues around high memory usage for the revisions page
> of wp-admin [0][1], it seems like getting a way to only load (for
> instance) the most recent revisions would be an interesting win to
> provide a smoother experience with revisions.
>
> [0] https://core.trac.wordpress.org/ticket/34560
> [1] https://core.trac.wordpress.org/ticket/24958
>
> PS: To provide some (more) context, there is an ongoing effort to support
> revisions in Calypso: https://github.com/Automattic/wp-calypso/pull/12733
> from which this enhancement request emerged.

New description:

 The post revisions REST endpoint currently has no support for pagination.
 While it works well for most usages with fairly low counts of revisions
 (WordPress.com limits the number at 25 for instance), on posts with a
 revision count in the hundreds (or even thousands), this can quickly yield
 unreasonably large (Mb+ of pure text) and long (several seconds on my
 "test" instances) responses.

 The API already supports pagination for a vast majority of ressources
 (posts, pages, categories, tags, users) and is normalised around using 2
 integer parameters: `page` (default: `1`)and `per_page` (default: `10`).

 I wonder if there is any reason why pagination was never implemented on
 that endpoint? Is it something potentially worth working on? Considering
 some of the past issues around high memory usage for the revisions page of
 wp-admin [0][1], it seems like getting a way to only load (for instance)
 the most recent revisions would be an interesting win to provide a
 smoother experience with revisions.

 [0] https://core.trac.wordpress.org/ticket/34560
 [1] https://core.trac.wordpress.org/ticket/24958

 PS: To provide some (more) context, there is an ongoing effort to support
 revisions in Calypso: https://github.com/Automattic/wp-calypso/pull/12733
 from which this enhancement request emerged.

--

Comment:

 Per today's REST API chat, supporting pagination and generally allowing a
 bit more flexibility with the revisions controller would also come in
 handy for Gutenberg.

 [attachment:40510.diff] adds support for the following query parameters
 for revisions:
 * `exclude`
 * `include`
 * `offset`
 * `order` (default 'desc')
 * `orderby` (default 'date')
 * `page` (default 1)
 * `per_page` (default not provided, falling back to using -1 with
 `WP_Query`, meaning no limit, for BC with current behavior)
 * `search`

 The implementation aligns closer with how the posts controller works.
 `WP_Query` is directly used instead of calling `wp_get_post_revisions()`,
 to be able to run a `SELECT FOUND_ROWS()` query and get the result. Since
 the function is only a simple wrapper for a query object anyway which sets
 default arguments, this can easily be handled in the controller itself.

 The revisions controller will now return `X-WP-Total` and `X-WP-
 TotalPages` headers and pagination link headers (if applicable) for
 collection requests, just how the posts controller does.

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