Wagtail API - how to customize the detail URL

Dan Braghiș — Fri, 13 Dec 2019 15:42:15 +0000

A while ago, a member of the Wagtail community wanted to customize the PagesAPIEndpoint to access the specific page detail view via its slug (/api/v2/pages/the-page-slug, rather than id (/api/v2/pages/123)

The Wagtail API builds on the Django REST Framework (DRF), so the natural place to check was the DRF docs. The generic views documentation page points to changing lookup_field, however that does not work because BaseAPIEndpoint.get_object_detail_urlpath from which PagesAPIEndpoint is derived uses pk explicitly. The next logical place was to override the detail_url method for the model serializer (ref: BaseSerializer and DetailUrlField, with no success.

Digging further into the Wagtail API implementation internals reveals that the API router gets the URL information from each endpoint via get_urlpatterns and the BaseAPIEndpoint defines them as

# https://github.com/wagtail/wagtail/blob/v2.7/wagtail/api/v2/endpoints.py#L340
return [
    url(r'^$', cls.as_view({'get': 'listing_view'}), name='listing'),
    url(r'^(?P<pk>\d+)/$', cls.as_view({'get': 'detail_view'}), name='detail'),
    url(r'^find/$', cls.as_view({'get': 'find_view'}), name='find'),
]

With that in hand, we can then define our own endpoint that can handle both id and slug as parameters for the detail view.

# api.py
from wagtail.api.v2.endpoints import PagesAPIEndpoint
from wagtail.api.v2.router import WagtailAPIRouter


class MyPagesAPIEndpoint(PagesAPIEndpoint):
    """
    Our custom Pages API endpoint that allows finding pages by pk or slug
    """

    def detail_view(self, request, pk=None, slug=None):
        param = pk
        if slug is not None:
            self.lookup_field = 'slug'
            param = slug
        return super().detail_view(request, param)

    @classmethod
    def get_urlpatterns(cls):
        """
        This returns a list of URL patterns for the endpoint
        """
        return [
            path('', cls.as_view({'get': 'listing_view'}), name='listing'),
            path('<int:pk>/', cls.as_view({'get': 'detail_view'}), name='detail'),
            path('<slug:slug>/', cls.as_view({'get': 'detail_view'}), name='detail'),
            path('find/', cls.as_view({'get': 'find_view'}), name='find'),
        ]

# Create the router. “wagtailapi” is the URL namespace
api_router = WagtailAPIRouter('wagtailapi')

api_router.register_endpoint('pages', MyPagesAPIEndpoint)

While the above works, slugs are only unique within a parent in Wagtail. It is, therefore, possible to have multiple pages with the same slug, but in different sections of the site (e.g.our-team in /about/our-team and /blog/our-team). This would lead to a MultipleObjectsReturned exception. To account for that, you need to do some defensive programming:

from django.core.exceptions import MultipleObjectsReturned
from django.shortcuts import redirect
from django.urls import reverse, path

from wagtail.api.v2.endpoints import PagesAPIEndpoint
from wagtail.api.v2.router import WagtailAPIRouter


class MyPagesAPIEndpoint(PagesAPIEndpoint):
    """
    Our custom Pages API endpoint that allows finding pages by pk or slug
    """

    def detail_view(self, request, pk=None, slug=None):
        param = pk
        if slug is not None:
            self.lookup_field = 'slug'
            param = slug
        try:
            return super().detail_view(request, param)
        except MultipleObjectsReturned:
            # Redirect to the listing view, filtered by the relevant slug
            # The router is registered with the `wagtailapi` namespace,
            # `pages` is our endpoint namespace and `listing` is the listing view url name.
            return redirect(
                reverse('wagtailapi:pages:listing') + f'?{self.lookup_field}={param}'
            )

    @classmethod
    def get_urlpatterns(cls):
        """
        This returns a list of URL patterns for the endpoint
        """
        return [
            path('', cls.as_view({'get': 'listing_view'}), name='listing'),
            path('<int:pk>/', cls.as_view({'get': 'detail_view'}), name='detail'),
            path('<slug:slug>/', cls.as_view({'get': 'detail_view'}), name='detail'),
            path('find/', cls.as_view({'get': 'find_view'}), name='find'),
        ]

# Create the router. “wagtailapi” is the URL namespace
api_router = WagtailAPIRouter('wagtailapi')

api_router.register_endpoint('pages', MyPagesAPIEndpoint)

Using this technique we can provide additional endpoint URL patterns and make the Wagtail API cater for even more project specific requirements.

Happy coding!

Wagtail + Hacktoberfest = ️

Dan Braghiș — Wed, 16 Oct 2019 15:03:59 +0000

wagtail / wagtail

A Django content management system focused on flexibility and user experience

Wagtail is an open source content management system built on Django, with a strong community and commercial support. It's focused on user experience, and offers precise control for designers and developers.

🔥 Features

A fast, attractive interface for authors
Complete control over front-end design and structure
Scales to millions of pages and thousands of editors
Fast out of the box, cache-friendly when you need it
Content API for 'headless' sites with de-coupled front-end
Runs on a Raspberry Pi or a multi-datacenter cloud platform
StreamField encourages flexible content without compromising structure
Powerful, integrated search, using Elasticsearch or PostgreSQL
Excellent support for images and embedded content
Multi-site and multi-language ready
Embraces and extends Django

Find out more at wagtail.org.

👉 Getting started

Wagtail works with Python 3, on any platform.

To get started with using Wagtail, run the following in a virtual environment:

pip install wagtail
wagtail start mysite
cd

…

View on GitHub

This year is our third #hacktoberfest. We have had a great number of contributions this Hacktober. Thank you to everyone who contributed so far!

How can I help? 👩‍💻👨‍💻

Head over to the #Hacktoberfest issues list on GitHub and pick any that is not being worked on.

Any and all contributions are welcome.

I don't know where to start 🤷‍♂️

To get started with Wagtail, see our docs, the Development section in particular. Try the Wagtail demo project or learn Wagtail at https://learnwagtail.com