13 Jul 2016

Introducing the Admin API

Over the past year, we have been working on a new internal REST API to power Wagtail's admin interface. Now that the initial version has landed on master, here's a summary of what this new API will bring to Wagtail

Karl Hobley

Developer, Torchbox

The Admin API makes it possible for Wagtail's client-side code to fetch content in the background and display it without having to reload the page. This brings more possibilities for improving the UI, as well as improving the developer experience for Wagtail's contributors.

Faster UI

Replacing janky page loads with fluid, animated transitions is a recent trend in web development and we hope to introduce some into Wagtail over the next year. This will be made possible by loading content in the background with the API, before rendering it in the browser without reloading the page.

The first UI feature you can expect to see rebuilt on the Admin API is a new explorer widget - see the video below. We hope to convert more actions (such as page locking) and interfaces (revisions, choosers) to the Admin API soon.

Cleaner code

We aim to make the Wagtail codebase as approachable to new contributors as possible. There are a few parts of the codebase where we can do better.

One example is chooser models. Here, the front-end, written in JavaScript, sends AJAX requests to the back-end, written in Python, which renders a HTML and JavaScript fragment. The HTML is processed and displayed in the modal and the JavaScript is executed using eval(), which performs actions in the browser such as closing the modal or executing a callback function.

Ideally, these chooser modals would be implemented entirely in JavaScript and use the front-end tooling that we set up at the Cape Town sprint. The data should be fetched from the API so it wouldn't need any custom backend code.

Another benefit to using the Admin API in this way is that individual components do not need to be concerned about business rules (custom permission model, multi-tenancy) as these would be implemented in the API.

Why a new API?

Wagtail already has an API (introduced in Wagtail 1.0) that can be optionally enabled, but which is focused on serving content to public browsers; only live, public content is available.

The Admin API gives access to all content that the logged-in user has permission to see. It also gives access to additional metadata, such as page status and updated times.

How is it implemented?

It is based on Wagtail's existing public API and built using the Django REST Framework.

Demo

Try out the API yourself at the following links: pages / images / documents (username/password are both "admin").