improving-drf-endpoints

Improving DRF Endpoints

Before you propose a contract test against the generated OpenAPI schema, check things already tried. Six PRs took that idea, and none merged.

Overview

Serializer fields are the source of truth for PostHog's entire type pipeline:

Django serializer → drf-spectacular → OpenAPI JSON → Orval → Zod schemas → MCP tools

Every help_text, every field type, every @extend_schema annotation flows downstream. A missing help_text means an agent guessing at parameters. A bare ListField() means z.unknown() in the generated Zod schema. Getting the serializer right means every consumer — frontend types, MCP tools, API docs — gets correct types and descriptions automatically.

When to use

• Editing or reviewing any file that defines a Serializer or ViewSet
• Fixing OpenAPI spec warnings or generated type issues
• Preparing an endpoint for MCP tool exposure
• Code review of API changes

Audit checklist

Triage: check the generated output first

Before diving into Python, look at the committed generated types to see what's broken. Find the generated files for the endpoint's product:

• Core API: frontend/src/generated/core/
• Product APIs: products/<product>/frontend/generated/

Each has two files:

• api.schemas.ts — TypeScript interfaces derived from serializers. Search for the serializer name and look for unknown types (bare ListField/JSONField), missing JSDoc descriptions (missing help_text), or overly generic Record<string, unknown> shapes.
• api.ts — API client functions. Check if the endpoint's operation exists at all — if missing, the viewset method likely lacks @extend_schema.

This tells you exactly which fields and endpoints to prioritize.

Serializer fields

Work through this list for every serializer and viewset you touch.

1. Every field has help_text — describes purpose, format, constraints, valid values
2. No bare ListField() or DictField() — always specify child= with a typed serializer or field
3. No bare JSONField() — create a custom field class with @extend_schema_field(TypedSchema)
4. SerializerMethodField has @extend_schema_field on its get_* method
5. ChoiceField has explicit choices= with all valid values listed
6. Avoid collision-prone enum field names — format, type, status, kind, level, mode, state, platform, provider clash with existing choices and fail CI under --fail-on-warn; pick a specific name or add an ENUM_NAME_OVERRIDES entry up front. A product enum's entry must point at a re-export in the product's backend/facade/enums.py, never at an internal module — an internal target goes stale invisibly when the product refactors (see serializer-fields.md)
7. Read vs write serializers are separate when input shape differs from output
8. Every success response is backed by a serializer — returning raw dicts or untyped lists means no generated types downstream