Serialization & Deserialization

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_api/_utilities/serializers.py
• src/flext_api/_protocols/base_serialization.py
• src/flext_api/_protocols/serialization.py
• src/flext_api/_typings/serialization.py
• src/flext_api/constants.py
• src/flext_api/history.json
• pyproject.toml

The Serialization & Deserialization system in the FLEXT API project provides a unified, protocol-agnostic framework for converting complex Python objects into portable formats (and vice versa). It supports multiple high-performance formats including JSON, MessagePack, and CBOR, integrated directly with Pydantic 2 for strict type validation.

This system is designed to handle API request/response payloads, storage entries, and internal message passing with consistent error handling and type safety. It leverages specialized libraries like orjson, msgpack, and cbor2 to ensure high performance in REST and WebSocket contexts.
Sources: src/flext_api/constants.py, pyproject.toml:23-35, src/flext_api/history.json

Core Serialization Architecture

The architecture relies on a series of protocols and base classes that define the contract for serialization operations. This ensures that different serialization formats can be swapped or extended without breaking the higher-level API logic.

Serialization Protocols

The system defines standard interfaces for encoders and decoders.

• BaseSerializer: The foundational protocol for all serialization handlers.
• JsonSerializer: Specialized for JSON handling using orjson.
• MsgpackSerializer: Specialized for binary MessagePack handling.
• CborSerializer: Specialized for Concise Binary Object Representation.

The diagram above shows the relationship between the base serialization protocol and its concrete implementations.
Sources: src/flext_api/_protocols/base_serialization.py, src/flext_api/_protocols/serialization.py

Supported Formats & Constants

FLEXT API uses StrEnum for type-safe format identification. This allows the system to route data to the correct serializer based on the Content-Type or internal configuration.

Serialization Formats

Format	MIME Type / Identifier	Implementation
JSON	application/json	orjson
MessagePack	msgpack	msgpack-python
CBOR	cbor	cbor2
Custom	custom	User-defined

Sources: src/flext_api/constants.py:168-175, src/flext_api/history.json, pyproject.toml:23-35

Type-Safe Data Adapters

The project utilizes Pydantic TypeAdapter instances to enforce strict validation during the serialization process. These adapters are centrally defined in the typings layer to ensure consistency across the domain and infrastructure layers.

Key Data Adapters

• API_JSON_VALUE_ADAPTER: Validates generic JSON values.
• BINARY_CONTENT_ADAPTER: Validates StrictBytes for binary payloads.
• REQUEST_BODY_ADAPTER: Validates complex request bodies (JsonMapping, str, or bytes).
• RESPONSE_BODY_ADAPTER: Validates API response bodies.

Sources: src/flext_api/_typings/serialization.py, src/flext_api/history.json

Data Flow: Request Serialization

When a request is built, it undergoes a normalization and validation process before being transmitted.

The flow shows how raw inputs are processed through RequestUtils and validated against models before final serialization.
Sources: examples/01_basic_usage.py:27-56, src/flext_api/history.json

Implementation Details

Utility Functions

The system exposes high-level utility functions for common tasks, such as packb (pack bytes) and unpackb (unpack bytes), which abstract the underlying protocol complexity.

• packb: Converts a dictionary or mapping into binary format (typically MessagePack or JSON).
• unpackb: Reverses the process, returning a Result object containing the deserialized data or an error.

Sources: tests/unit/test_smoke.py:96-107, src/flext_api/_utilities/serializers.py

Handling Webhooks

Webhooks utilize specific serialization logic to verify signatures and process incoming JSON mappings. The WebhookAlgorithm enum defines supported HMAC algorithms (sha256, sha512).
Sources: src/flext_api/constants.py:146-153, src/flext_api/history.json

Summary

Serialization and Deserialization in FLEXT API serve as a high-performance bridge between Python's rich object model and standard wire formats. By combining strict Pydantic validation with optimized libraries like orjson, the system ensures that data integrity is maintained across all communication channels, including RESTful APIs and binary WebSockets.