[RFC] Wagtail admin API

Looking to get some feedback on this new feature that I think would help us to greatly improve the maintainability of parts of the admin interface and may lead to user interface improvements in the future.

The initial proposal can be found here: https://groups.google.com/forum/#!topic/wagtail-developers/dNQ9LEaenyI

Background

We’ve recently been discussing refactoring parts of the Wagtail admin interface to give better separation between Python and JS. This will help us to simplify the modal workflow system that is currently very difficult to modify.

We’ve also discussed making the explorer and search interfaces more JavaScript driven.

Why an API?

In order to implement these features, we need a place where the new interfaces can fetch data from. I propose creating an REST API for this.

The main advantage of creating an API is that we can drive all these interfaces from a single place, so we can concentrate on creating a single rock-solid API and all the new interfaces will benefit from it. Unit testing APIs is also easier as JSON is much easier to parse and check than HTML.

Why not “Wagtail API”?

The wagtailapi module (introduced in 1.0) is focused on serving content out to external clients without admin access. For the admin interface, we need more features such as browsing draft pages and seeing permissions/page state. For the modal-workflow refactor we also need access to snippets, which wagtailapi doesn’t support.

The Admin API will be very similar and share a lot of code with the existing API.

The API

The API will be heavily based on the existing wagtailapi module and will include some features that I’d like to see in v2. The new API will not be versioned and may change in backwards-incompatible ways between Wagtail releases. So the API can change to suit needs of new Wagtail features when needed.

To save time I’ll just mention the differences from the wagtailapi module:

1) Authentication

Like the rest of the admin interface, the new API will use Django’s auth module and session cookie for authentication. The same user permissions that exist in the admin interface will be applied to the admin API.

2) Draft and private pages

All pages, including draft and private pages, are visible in the API. There will be three new fields added, “status” (string), “has_page_view_restriction” (boolean) and “has_children” (boolean) so the existing UI can be replicated. All these fields will be in “meta”

3) Selecting multiple page types (wagtailapi v2 feature)

The ?type= filter will be able to take a comma-separated list of page types. This is required for the page chooser modal.

4) Image thumbnails

A thumbnail_url field will be added to the images endpoint containing the URL of the max-165x165 rendition.

5) child_of/descendant_of filters take special “root” value representing the root page

For example, ?child_of=root will get the children of the root page

6) html_url, slug, first_published_at, updated_at fields on pages (wagtailapi v2 feature)

All live pages will be given a html_url if they are in a site, linking to where they exist on the frontend

The slug, first_published_at, updated_at fields will be taken straight from the modal

html_url, first_published_at, updated_at will appear in the “meta” section. slug will appear alongside other data fields.

7) parent field on page listings

The parent link will be added to the page listing.

Implementation

The new API will be built using Django REST Framework and reuse parts of the existing wagtailapi module.

The core part of the API will be implemented in Wagtail admin. All endpoints will be implemented in their respective module (except for pages which will be implemented in wagtailadmin) and endpoints will be registered with a hook.

Initially, endpoints will be implemented for pages, images, documents and snippets.

The URL of the endpoints will be of the form /admin/api/{pages,images,documents}/. The snippet API URL will contain a model name: /admin/api/snippets/app_name.ModelName/.

Some refactoring is required in the wagtailapi module to allow it to be reused in this way. Also, as it’s currently a contrib module, we need to think about how we’re going to restructure it so core modules don’t have to depend on a contrib module.

[kaedroho]

Admin API merged into Wagtail 1.6

[SalahAdDin]

Ah, thanks, it’s a great thing!