Question: serializer_class instead of api_fields

[e-kondr01]

To expose Page fields over API and specify their serialization, Wagtail API v2 uses Page's attribute api_fields.

Wagtail-Pipit docs say that you use Page's attribute serializer_class for this. What were the considerations when changing it from the default wagtail api's implementation?

[marteinn]

Hi @e-kondr01!

Just to clarify, Pipit does not use the Wagtail API, instead we use a system where we, using a custom API, locates pages using their path and transforms them to data using serializers. serializer_class is a property added by us to connect a Page with a serializer.

With this in mind, to your question, there are no considerations since we do not use the API. In fact api_fields can also be added to a page and still accessed through the regular Wagtail API.

We originally started with using api_fields several years back as a data source, but found it too limiting when you want to do custom work, such as pass extra context and you can only add properties, which is limiting too.

[e-kondr01]

Understood. I see why you would want to use a whole serializer class instead of serializers for fields only.

Are there any utilities that may be missing when using Pipit for API, compared to Wagtail API V2?

For instance, I see wagtail api has additional serializer field classes apart from wagtail_serializers.StreamField that Pipit uses in its BaseSerializer.

[marteinn]

@e-kondr01 The Wagtail API sort of builds up a dynamic serializer based on the Page structure and api_fields, in this process certain fields are automatically mapped, this magic is lost in Pipit as we have a more explicit approach of defining serializers. But other then that, everything else should work, the Wagtail API is built on rest framework and serializers.

This is sort of how the Wagtail auto mapping works, if you want to play with it.
(We used this approach before choosing to go with manually defined serializers).

from wagtail.api.v2.serializers import get_serializer_class, PageSerializer

# self here is the page

fields = [f.name for f in self.api_fields]
child_serializers = {
    f.name: f.serializer
    for f in self.api_fields
    if f.serializer
}

serializer_class = get_serializer_class(
    type(self),
    fields,
    [PagesAPIViewSet.meta_fields],
    child_serializer_classes=child_serializers,
    base=PageSerializer
)
serializer = serializer_class(self)
data = serializer.data

[e-kondr01]

Got it, thanks for clarifying. This info may be useful for other people discovering wagtail-pipit as well. Maybe you could consider expanding documentation on Backend Developer Guide a bit.