API development

Guidance for Wagtail core contributors working on the v3 API transport layer first defined in RFC 115.

OpenAPI snapshot workflow

CI asserts that api.get_openapi_schema() matches wagtail/api/v3/tests/snapshots/openapi.json.

When you add or change endpoints intentionally, regenerate the snapshot and commit the changes:

make openapi-snapshot

For guidance on the v3 API’s schema discovery endpoints and how read and write schemas are generated, see the schema discovery guide.

Type checking

The v3 API package is type-checked with ty (configured in [tool.ty] in pyproject.toml). Checking is scoped to wagtail/api/v3 only.

Pagination

List endpoints use @paginate with WagtailLimitOffsetPagination, defined in wagtail/api/v3/pagination.py. Responses use Ninja’s native envelope: {"count": N, "items": [...]}. WAGTAILAPI_LIMIT_MAX is enforced in the paginator.

RFC 7807 errors

Register handlers via register_exception_handlers(api) in wagtail/api/v3/errors.py. Tests should use assert_problem_response from wagtail.api.v3.tests.base.

Contrib app endpoints

Endpoints for models owned by a separate app (images, documents, snippets, locales, redirects) live in that app’s api/v3 package, and the app registers its router from its own AppConfig.ready(). This keeps wagtail.api.v3 free of imports from apps a project might not install.

Tests and the swappable page model

To support custom base page models, make sure to import Page from wagtail.test.utils rather than wagtail.models, and add PageFixturesMixin to any test case that loads page fixtures such as demosite.json.