Skip to content

Serializers

Overview

The serializers in the notifications app define the API contract between backend and frontend.

They are responsible for: - shaping response data - validating incoming request payloads - providing a stable interface for clients

They are transport-layer only and do not contain business logic.

Serializer Types

NotificationSerializer

Represents a single notification in the user inbox.

Adds: - is_read (derived from read_at) - actor_id (without embedding full user object)

Used in: - notification list endpoints - notification detail views

NotificationGroupSerializer

Represents a grouped notification response.

Fields: - group_key - count - unread_count - latest (serialized notification payload)

Used in: - collapsed notification feeds

PushDeviceUpsertSerializer

Validates incoming push device registration data.

Fields: - provider - token - device_info (optional)

Responsibilities: - ensures valid provider choice - normalizes device_info to {}

Used in: - device registration endpoints - device heartbeat endpoints

PushDeviceOutSerializer

Represents a push device in API responses.

Fields: - id - provider - token - is_active - device_info - created_at - last_seen_at

Used in: - debug/admin endpoints - device management APIs

BulkMarkReadSerializer

Validates bulk mark-read requests.

Fields: - ids (list of UUIDs)

Constraints: - non-empty list - maximum length enforced

Used in: - bulk read endpoints

NotificationRuleMetaSerializer

Represents a single notification rule from the registry.

Includes: - identity (key) - display metadata (display, category, severity) - preference mapping (pref, default, channels) - navigation (route, params, entity) - templates (optional) - UX flags (help, actor_required)

Used in: - registry metadata endpoint

NotificationRegistryMetaResponseSerializer

Wraps registry metadata response.

Fields: - version (hash for caching) - rules (list of rule metadata)

Used in: - frontend configuration endpoints

Responsibilities

Serializers layer

  • validate request data
  • shape API responses
  • provide consistent field naming
  • normalize inputs (e.g. device_info)

Services layer

  • create notifications
  • resolve preferences
  • apply business rules
  • handle deduplication

Tasks layer

  • handle delivery retries
  • process async operations

What serializers do not do

Serializers do not:

  • query complex business logic
  • enforce permissions
  • trigger side effects
  • send notifications
  • interact with providers

Validation Philosophy

  • keep validation lightweight and structural
  • avoid embedding business rules
  • normalize inputs early
  • rely on services for deeper validation

Best practices

  • keep serializers small and focused
  • avoid nested heavy objects unless necessary
  • use explicit fields rather than implicit model exposure
  • derive convenience fields (e.g. is_read) when helpful
  • enforce limits on bulk operations

Summary

The notifications serializers provide a clean and stable API contract.

They ensure: - predictable request validation - consistent response shapes - separation from business logic

This keeps the system: - maintainable - testable - frontend-friendly