Serialization Design

Stream APIs

The stream API allows the user to send the JSON object directly to Cosmos DB.

• Provides performance benefits by avoiding unnecessary serialization.
• Allows users to use any serialization implementation.
• Enables the ability to just pass the stream through the application without deserializing it.

Typed APIs

The typed APIs provide a simple interface for working with C# objects. This is a high level overview of how the typed APIs work:

Application code -> Typed API -> CosmosJsonSerializer -> Stream API

• The typed APIs always deserialize the response.
  • Ensures the response is read and disposed of correctly.
  • Avoids the need for user to wrap everything in using statements.
  • Avoids common mistakes that cause memory leaks when working with IDisposable.
• All the typed APIs call the stream API implementation.
• Typed APIs use the CosmosJsonSerializer to handle all the stream conversion.
  • This can be set on the CosmosClient creation, and allows custom implementations.
  • The system owned types like Database and Container operations are always handled by the default implementation. This avoids users from needing to add custom handling based on the types owned by the SDK.