Migrating from the v2 API¶
The v3 API has major differences with v2. We aim for all v2 capabilities to be present or replicable in v3, with exceptions. Treat moving to it as a migration to a new API: audit each client against the v3 behaviour described in this reference.
The v2 API is planned for deprecation in favor of v3. It currently remains available, but we recommend planning your migration now. See the deprecation timeline below.
Deprecation timeline for the v2 API¶
Wagtail 8.1: the v2 API remains available and supported, with no changes. We recommend trying v3 on your project, and sharing feedback on anything that makes migrating difficult.
Wagtail 8.2: the v2 API is deprecated, and using it raises deprecation warnings. It is also published as a separate package for projects that need more time to migrate. We plan for the v3 API to be stable from this release.
Wagtail 8.3 (LTS): the v2 API remains included, with deprecation warnings.
Wagtail 9.0: the v2 API is removed from Wagtail. Projects that still use it can switch to the separate package.
Only the v2 API’s endpoints, views, and serializers are affected. APIField and api_fields are shared with the v3 API, and are not deprecated.
Comparison of v2 and v3 APIs¶
Here is a comparison of the two versions across high-level areas relevant for compatibility.
Area |
v2 |
v3 |
|---|---|---|
Framework |
Django Ninja and Pydantic |
|
Operations |
Read-only lists, detail, and find |
Read/write, actions, and revisions |
Resources |
Pages, images, documents, redirects, by registered endpoints |
All of v2 and sites, locales, snippets, schema, and |
Authentication |
Public by default, DRF-configurable auth |
Anonymous reads by default, Wagtail-provided bearer tokens |
Page visibility |
Public/live queryset by default |
Public/live anonymously; drafts with change or publish permission when authenticated |
Pagination envelope |
|
|
Field projection |
Rich |
Not supported in favor of fixed generated schemas |
API fields |
DRF serializers, sources, computed fields |
Read compatibility plus typed Pydantic schemas and explicit writable fields |
Unknown queries |
Rejected |
Unknown arbitrary field filters are often skipped |
Ordering encoding |
Comma-oriented v2 filters |
Repeated/list query parameters |
Find |
Generic for registered endpoints |
Pages and redirects only |
Rich text |
Multiple output formats |
Multiple output formats and subset for input |
StreamField |
Read representation |
Read and full-field write |
Errors |
DRF message dictionaries |
Problem Details |
OpenAPI / discovery |
No schema support |
OpenAPI 3.1 and authenticated schema discovery |
Frontend cache |
Pages, images, documents |
Pages, images, documents, redirects |
See the v3 reference for the definitive per-endpoint details, and the schema discovery guide for how v3 fields and write schemas are generated.
High-risk migration areas¶
Some v2 capabilities have no direct v3 equivalent, or behave differently enough to break a naive port. Pay particular attention to the following:
Lack of
?fields=support. v3 exposes fixed schemas.DRF
APIField(serializer=...)serializers support. v3 has a temporary compatibility layer but the output may differ. Some fields have direct replacements, such aswagtail.images.api.v3.fields.ImageRenditionFieldreplacingwagtail.images.api.fields.ImageRenditionField(see the image renditions guide). Other fields can be reimplemented as a subclass ofwagtail.api.v3.fields.FieldSerializer.Different error responses. DRF messages vs. Problem Details. Different HTTP status codes for some errors.
Different list envelope. v2 returns
{"meta": {"total_count": ...}, ...}; v3 returns{"count": ..., "items": [...]}and rejects alimitof0.Authenticated page visibility differs. v2 defaulted to the public live queryset. A v3 bearer-authenticated request sees the pages the user has change or publish permission for, including draft-only pages.
Custom v2 endpoints. They may be replace-able with v3’s generic endpoints, or require creation of new custom endpoints.