Wagtail Documentation
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
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 (or a subclass such as PageListingPagination in routers/pages.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.