Design API v3

[etj]

Why

v2 has two problems a patch can't fix without breaking existing clients:

• It's built on django-dynamic-rest, whose automatic joins and sideloading (include[]/filter{}) are hard to predict from the serializer alone, and page size is uncapped.
• It has no OpenAPI schema, so nothing documents an endpoint automatically.

What

v3 is a clean break, not a v2 migration. Decisions made:

• Plain DRF — ModelSerializer + explicit select_related/prefetch_related, no dynamic-rest.
• A single ?fields= parameter replaces DREST's include[]/exclude[]/ filter{}/sort[], and prunes the query as well as the response.
• Trailing slash is required on every v3 path — one canonical URL per endpoint.
• Every v3 viewset must declare permission_classes explicitly; REST_FRAMEWORK has no project-wide default, so an omission means world-writable.
• OpenAPI via drf-spectacular, scoped to v3 only. It was dropped from GeoNode entirely once before because it conflicted with dynamic-rest; safe to bring back now that v3 doesn't use it.
• File layout follows v2's own per-app convention, one version segment deeper: shared infrastructure at geonode/api/v3/, each resource under its owning app's api/v3/. v2 itself is not touched or renamed.

[etj]

Implementation notes

• ?fields= must prune the query, not just the response. Filtering the serializer's output alone is cosmetic -- the performance goal only lands if unrequested fields also skip their select_related/prefetch_related. Drive both from one place per resource (e.g. a field -> {select, prefetch} map), not two.
• Trailing slash required is DRF's own default, not an invented rule -- DefaultRouter(trailing_slash=True). v2 is inconsistent (optional on the shared DynamicRouter, required on harvesting/management-command routers); v3 picks one and sticks to it.
• drf-spectacular has failed here before. It was dropped from GeoNode entirely in redoc is broken #14201/[Fixes #14201] Dropped spectacular, replaced with docstrings for API endpoints #14202 because /api/v2/schema/redoc/ crashed -- the generator walks every registered endpoint and asserts each view carries a spectacular AutoSchema; v2's dynamic-rest viewsets didn't. Don't set DEFAULT_SCHEMA_CLASS globally in REST_FRAMEWORK -- that's exactly what caused it. Scope it per-viewset (only v3 viewsets carry the schema class) and filter v2 out via a PREPROCESSING_HOOK, so the generator never inspects a v2 view. Also exclude the schema-serving views themselves (/api/v3/schema/*) from that same hook -- they live under /api/v3/ but don't carry a spectacular schema either, so leaving them in reproduces the identical crash against spectacular's own view.
• File layout, not yet done: shared v3 infra should live at geonode/api/v3/, each resource under its owning app (geonode/groups/api/v3/, geonode/services/api/v3/), one version segment deeper than v2's existing per-app convention.
  v2 itself does not move. We looked at retro-versioning v2 into <app>/api/v2/ for symmetry and rejected it: HTTP routes wouldn't change, but geonode_mapstore_client imports geonode.api.urls.router directly and depends on getting the same object back, so that import would break -- and we don't control every downstream package that subclasses v2 API classes by direct import (the GeoNode Project Template pattern encourages exactly that). Not worth the blast radius for cosmetic symmetry.
• We considered bare function-based views for less framework ceremony; kept class-based ModelViewSet because moving all the way to bare functions would quietly reinvent hand-rolled pagination, validation, and (worse) the automatic fetch-then-check-object-permission ordering that GenericAPIView.get_object() gives for free. @api_view function views remain a reasonable middle ground for anything more RPC-shaped than CRUD later.