From 3dc592db6e3f3b5422e5a94e5c0f81ab092169a4 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Thu, 12 Jul 2018 16:22:29 +0100 Subject: [PATCH 1/3] Changes API --- text/xxx-changes-api.md | 109 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 text/xxx-changes-api.md diff --git a/text/xxx-changes-api.md b/text/xxx-changes-api.md new file mode 100644 index 00000000..5f78152b --- /dev/null +++ b/text/xxx-changes-api.md @@ -0,0 +1,109 @@ +# RFC X: Changes API + +* RFC: X +* Author: Karl Hobley +* Created: 2018-07-12 +* Last Modified: 2018-07-12 + +## Abstract + +This RFC proposes extending Wagtail's API to allow fetching all modifications to pages +since a point in time. + +Use cases include periodically re-rendering static sites and replication with external +services. + +## Specification + +We will add a new optional endpoint at ``/api/v2/pages/changes/`` which returns a list of modifications. + +This specification is inspired by the [Realtime Paged Data Exchange](https://www.openactive.io/realtime-paged-data-exchange/) specification from OpenActve. + +### Basic usage + +Performing a GET request will return a list of modifications with the oldest first. +If two modifications were created at exactly the same time, the ID will be used to +order them. + +``` +GET /api/v2/pages/changes/ +``` + +```json +{ + "meta": { + "total_count": 10, + "next": "http://example.com/api/v2/pages/changes/?after=2018-07-12T16:03:00Z/1" + }, + "items": [ + { + "time": "2018-07-12T16:03:00Z", + "id": 1, + "kind": "publish", + "data": { + "id": 1, + "meta": { + "type": "home.HomePage", + ... + }, + "title": "Home", + ... + } + } + ] +} +``` + +### Pagination + +There's no defined number of items that each response should return. It's possible that +responses may be filtered in flight so the number of items in each response may be different +or even zero. + +In order to fetch all updates, the client must keep following the "next" URL until this URL no +longer changes. + +### Modifications + +There are two of modification: ``publish`` and ``unpublish``. For each page, only the latest modification will be returned. + +#### ``publish`` + +This modification kind is used when the page has been published for both the initial publish and subsequent publishes. The full detail representation of the pages latest content is nested in the modification in the ``data`` property. + +Note: When a live page is moved, this will also count as a modification in the changes API. + +```json +{ + "time": "2018-07-12T16:03:00Z", + "id": 1, + "kind": "publish", + "data": { + "id": 1, + "meta": { + "type": "home.HomePage", + ... + }, + "title": "Home", + ... + } +} +``` + +#### ``unpublish`` + +This modification kind is used when the page has been unpublished. + +```json +{ + "time": "2018-07-12T16:03:00Z", + "id": 1, + "kind": "unpublish", +} +``` + +### URL parameters + +#### ``?after=[/]`` + +This limits the results to only show modifications after the specified date/id. From a47e5f0b18a46e767b697f4c2efafba78e01eca3 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Thu, 12 Jul 2018 16:23:32 +0100 Subject: [PATCH 2/3] Set number to 30 --- text/{xxx-changes-api.md => 030-changes-api.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename text/{xxx-changes-api.md => 030-changes-api.md} (98%) diff --git a/text/xxx-changes-api.md b/text/030-changes-api.md similarity index 98% rename from text/xxx-changes-api.md rename to text/030-changes-api.md index 5f78152b..1d5c60d1 100644 --- a/text/xxx-changes-api.md +++ b/text/030-changes-api.md @@ -1,6 +1,6 @@ -# RFC X: Changes API +# RFC 30: Changes API -* RFC: X +* RFC: 30 * Author: Karl Hobley * Created: 2018-07-12 * Last Modified: 2018-07-12 From bd70a79315a4014b8768763ac672b154f4be858f Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Thu, 12 Jul 2018 16:29:51 +0100 Subject: [PATCH 3/3] Tweaks --- text/030-changes-api.md | 64 +++++++++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/text/030-changes-api.md b/text/030-changes-api.md index 1d5c60d1..b38a710e 100644 --- a/text/030-changes-api.md +++ b/text/030-changes-api.md @@ -7,23 +7,46 @@ ## Abstract -This RFC proposes extending Wagtail's API to allow fetching all modifications to pages -since a point in time. +This RFC proposes extending Wagtail's API to allow fetching all modifications +to pages since a point in time. -Use cases include periodically re-rendering static sites and replication with external -services. +Use cases include periodically re-rendering static sites and replication with +external services. + +This specification is inspired by the +[Realtime Paged Data Exchange](https://www.openactive.io/realtime-paged-data-exchange/) +specification from OpenActve. ## Specification -We will add a new optional endpoint at ``/api/v2/pages/changes/`` which returns a list of modifications. +We will add a new endpoint at ``/api/v2/page-changes/`` which returns a list of +modifications. + +### Configuration + +The endpoint will not be enabled by default. To enable it, developers will have +to add the following +to their API router: + +```python + +# api.py -This specification is inspired by the [Realtime Paged Data Exchange](https://www.openactive.io/realtime-paged-data-exchange/) specification from OpenActve. +from wagtail.api.v2.endpoints import PagesAPIEndpoint, PageChangesAPIEndpoint +from wagtail.api.v2.router import WagtailAPIRouter + +api_router = WagtailAPIRouter('wagtailapi') + +api_router.register_endpoint('pages', PagesAPIEndpoint) +api_router.register_endpoint('page-changes', PageChangesAPIEndpoint) + +``` ### Basic usage -Performing a GET request will return a list of modifications with the oldest first. -If two modifications were created at exactly the same time, the ID will be used to -order them. +Performing a GET request will return a list of modifications with the oldest +first. If two modifications were created at exactly the same time, the ID +will be used to order them. ``` GET /api/v2/pages/changes/ @@ -33,7 +56,7 @@ GET /api/v2/pages/changes/ { "meta": { "total_count": 10, - "next": "http://example.com/api/v2/pages/changes/?after=2018-07-12T16:03:00Z/1" + "next": "http://example.com/api/v2/page-changes/?after=2018-07-12T16:03:00Z/1" }, "items": [ { @@ -56,22 +79,26 @@ GET /api/v2/pages/changes/ ### Pagination -There's no defined number of items that each response should return. It's possible that -responses may be filtered in flight so the number of items in each response may be different -or even zero. +There's no defined number of items that each response should return. It's +possible that responses may be filtered in flight so the number of items +in each response may be different or even zero. -In order to fetch all updates, the client must keep following the "next" URL until this URL no -longer changes. +In order to fetch all updates, the client must keep following the "next" URL +until this URL no longer changes. ### Modifications -There are two of modification: ``publish`` and ``unpublish``. For each page, only the latest modification will be returned. +There are two of modification: ``publish`` and ``unpublish``. For each page, +only the latest modification will be returned. #### ``publish`` -This modification kind is used when the page has been published for both the initial publish and subsequent publishes. The full detail representation of the pages latest content is nested in the modification in the ``data`` property. +This modification kind is used when the page has been published for both the +initial publish and subsequent publishes. The full detail representation of the +pages latest content is nested in the modification in the ``data`` property. -Note: When a live page is moved, this will also count as a modification in the changes API. +Note: When a live page is moved, this will also count as a modification in the +changes API. ```json { @@ -107,3 +134,4 @@ This modification kind is used when the page has been unpublished. #### ``?after=[/]`` This limits the results to only show modifications after the specified date/id. +The date must be ISO 8601 format.