Join #headless
on Slack


REST is one API option for Headless Wagtail

REST (or representational state transfer) was introduced in 2000 as a simpler approach to machine-to-machine communication using the HTTP protocol. Since REST was introduced, RESTful APIs have proliferated across the web to the point where they're essentially the default standard for modern APIs. Many headless content management systems use either RESTful architecture or GraphQL for their APIs. Both options work with Headless Wagtail, so let's explore the upsides and downsides of choosing REST.

Upsides of a REST API

  • Requests can be sent using common software like cURL or through web browsers.
  • The REST standards are open source and relatively simple to learn.
  • REST uses standard HTTP actions like GET, POST, and PUT.
  • REST operations require less bandwidth then other comparable technologies (such as SOAP).
  • REST is stateless on the server-side, so each request is processed independently.
  • Caching is manageable with REST.
  • REST is more common currently and there are many more tools available to support REST.
  • The REST API is a native feature of Wagtail with some functionality already built in.

Downsides of a REST API

  • Sometimes, multiple queries are required to return the necessary data.
  • REST isn't always efficient if a query requires access to multiple endpoints.
  • Requests to REST APIs can return extra data that's not needed.
  • REST depends on fixed data structures that can be somewhat difficult to update.

Alternative REST options

If you don't want to use Wagtail's built-in REST API, you can build your own using the Django REST framework. Remember, Wagtail is just Django!

REST Resources

Official Wagtail documentation on building a public-facing API

Wagtail API tutorial from


13 December 2019

Wagtail API - how to customize the detail URL

Customize the Wagtail API endpoints to suit your needs.