· Maatwerk en automatisering · Marco Polderman

Wagtail 8.1's API: waarom Django Ninja, en wat het betekent voor je frontend

Wagtail 8.1's nieuwe API draait op Django Ninja, niet op DRF. Wat was de afweging, en wat betekent het als een eigen team of designbureau je frontend bouwt?

pexels-picjumbocom-196645-scaled

De nieuwe v3 API van Wagtail draait op Django Ninja, niet op Django REST Framework (DRF). Op 11 november legde het Wagtail-team uit waarom. Gebruik je Wagtail headless, of bouwt een eigen team of designbureau je frontend? Dan laat die keuze zien waar je op bouwt, en hoe lang je erop kunt bouwen.

Dit is het derde stuk in een korte reeks: eerst de release, toen de headless-demo, nu de API-keuze zelf.

Eerst de lijn: release, demo, API-keuze

De release. Wagtail 8.1 (3 november) breidde de v3 API uit met schrijfbare content, StreamField-schema's en workflow-acties.

De headless-demo. Op 5 november volgde bakerydemo-headless: de Wagtail-demo met een Next.js-frontend, gevoed door v3. Live preview in de CMS blijft gewoon werken.

De API-keuze. Op 11 november legden Sage Abdullah en Thibaud Colas van het Wagtail-team uit waarom v3 op Django Ninja is gebouwd, en wat DRF beter doet.

Wat v3 kan, en wat 8.1 eraan toevoegde

v3 verscheen in Wagtail 8.0. Je kunt er niet alleen mee lezen: na inloggen maak en bewerk je er ook pagina's, afbeeldingen, documenten en snippets mee, inclusief revisies, rich text en StreamField. De API levert een OpenAPI 3.1-schema en foutmeldingen volgens de standaard RFC 7807.

Versie 8.1 vulde de gaten voor complexere contentstructuren:

  • Schrijven naar TypedTableBlock, geneste inline-relaties en workflow-acties.
  • Schema's voor StreamField-blokken, voor lezen én schrijven.
  • Meer schemadetail voor ForeignKey, ManyToManyField, GenericRelation en redirects.
  • Betere omgang met relaties over meerdere niveaus, multi-table inheritance en verwijzingen naar zichzelf.
  • Betere prestaties voor grotere projecten.

De oude v2 API bestaat nog. Die is alleen-lezen, draait op DRF en wordt op termijn uitgefaseerd.

DRF of Django Ninja: de afweging van het Wagtail-team

DRF is de gevestigde keuze. Volgens het Wagtail-team zit DRF bij ongeveer de helft van alle Django-downloads, Ninja bij zo'n 5%. Toch koos Wagtail voor Ninja.

Waarom Ninja

  • Het schema volgt uit type hints en OpenAPI zit ingebouwd. Bij DRF is schemageneratie geen kerndoel; daar gebruik je meestal het extra pakket drf-spectacular.
  • Endpoints blijven compact: functieviews met Pydantic-schema's in plaats van uitgebreidere serializers.
  • Het past bij de typing-richting die Wagtail en de Python-wereld opgaan.

Wat DRF beter doet

  • Klassegebaseerde permissies sluiten goed aan op Wagtails PermissionPolicy. Ninja heeft geen eigen permissieklassen, dus Wagtail bouwde inloggen en API-tokens zelf.
  • Filteren, pagineren en versiebeheer zijn volwassener, onder meer via django-filter.
  • Het ecosysteem is veel groter.

Onderhoud

DRF heeft geen afhankelijkheden, maar de maintainers zoeken een nieuwe thuisbasis. Ninja heeft één hoofdauteur, die nieuwe maintainers overweegt, en is vooral een laag bovenop Pydantic.

De blog is eerlijk over de prijs. Om de API gelijk te laten lopen met de formulieren in de CMS schreef Wagtail veel dynamische schemacode, die de auteurs zelf verre van ideaal noemen.

Hun conclusie: er is niet per se een goed of fout antwoord. Ninja is compacter en sterker in typing en OpenAPI. DRF is sterker in alles rond een endpoint en heeft een groter ecosysteem, maar ontwikkelt trager.

Wat dit betekent voor je frontend

Je frontend ziet een contract, geen framework. Een Next.js-site, een app of een koppeling praat met het OpenAPI 3.1-schema van v3. Daaruit genereer je getypte clients of SDK's; Wagtail levert daar ingebouwde endpoints voor. Of daarachter Ninja of DRF draait, merkt je frontendteam niet. De keuze blijft binnen de contentlaag.

Schrijven gaat via dezelfde API. Een import, een koppeling met een ander systeem of een AI-agent die concepten klaarzet: het loopt allemaal via dezelfde API, met inloggen en rechten. Dat scheelt maatwerk dat je anders per koppeling apart bouwt.

Eigen endpoints blijven mogelijk. Wagtail is gewoon Django. Heeft een project iets nodig dat niet in v3 zit, zoals een zoekfunctie op maat of een koppeling met een boekingssysteem, dan bouw je dat ernaast. In Ninja, voor één lijn met v3, of in DRF als een team daar al mee werkt.

Draait je site headless op v2? Plan de overstap. v2 werkt voorlopig nog, maar wordt uitgefaseerd. Neem de overstap naar v3 mee in een gewone onderhoudsronde, in plaats van te wachten tot het moet.

Voor designbureaus: jullie frontend, onze contentlaag

FlevoDevs doet geen design. Dat laten we bewust aan bureaus en ontwerpers. Wat we wel doen, is de Wagtail/Django-kant erachter: het contentmodel, de StreamField-blokken en de API waar jullie frontend mee praat. Headless als dat past, klassiek als dat beter werkt.

Jullie blijven eigenaar van het ontwerp en de klantrelatie. Wij werken whitelabel en benaderen jullie klanten niet zelf. Na een aanvraag krijg je binnen twee werkdagen een inschatting in dagen. Zo werkt samenwerken met FlevoDevs als bureau.

Zelf een Wagtail-project of headless opzet in gedachten?

Twijfel je of headless bij je organisatie past? Of draai je al op Wagtail en wil je weten wat v3 voor je site betekent? Plan een kennismaking, dan kijken we samen naar je contentstructuur en de logische volgende stap. Meer over onze aanpak lees je bij Wagtail en Django development.

Wie de API verder wil volgen: op Wagtail Space (18–20 november) gaan twee talks over wat v3 mogelijk maakt. En via RFC 118 vraagt het Wagtail-team om feedback op de plannen voor de volgende release.

Bron: DRF vs. Django Ninja: Wagtail 8.1's API schema, Wagtail-blog, 11 november 2026.

Lees ook

Alle berichten

We gaan de samenwerking graag met je aan!

Herken je dit in je eigen bedrijf? Plan een kennismaking, dan kijken we samen wat het voor jouw situatie betekent. Je krijgt een eerlijke inschatting, ook als dat betekent dat je bij ons niks hoeft af te nemen.

Dertig minuten, online of bij ons in Lelystad

Bel 0320 320 050 Plan een kennismaking