DevOp.Toon.API 0.1.8

DevOp.Toon.API

DevOp.Toon.API adds ASP.NET Core MVC formatter support for TOON.

Installation

dotnet add package DevOp.Toon.API

Features

• Registers TOON MVC formatters with AddToon(...)
• Supports text/toon and application/toon
• Reuses DevOp.Toon for TOON encoding, decoding, and options
• Uses Base64String byte-sequence encoding by default for byte[], List<byte>, and IEnumerable<byte>
• Allows per-request response encode overrides through X-Toon-Option-* headers
• Adds TOON media types to ASP.NET Core response compression options

Basic Usage

using DevOp.Toon.API;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddControllers()
    .AddToon();

AddToon() uses the compact columnar encoder profile by default:

• ignores null or empty values
• excludes empty arrays
• uses comma delimiters
• uses one-space indentation
• keeps key folding off
• writes object arrays in columnar layout

Override only the values your API needs to change:

builder.Services
    .AddControllers()
    .AddToon(options =>
    {
        options.Encode.Indent = 2;
        options.Encode.IgnoreNullOrEmpty = false;
    });

Response Compression

AddToon() adds application/toon and text/toon to ASP.NET Core response compression options. The application still controls whether response compression middleware is enabled:

builder.Services.AddResponseCompression();

var app = builder.Build();

app.UseResponseCompression();
app.MapControllers();

Per-Request Response Encode Overrides

Callers can override response encoding behavior for a single request by sending request headers in the format X-Toon-Option-<OptionName>: <value>.

Example:

GET /products
Accept: application/toon
X-Toon-Option-IgnoreNullOrEmpty: true
X-Toon-Option-ExcludeEmptyArrays: true
X-Toon-Option-ObjectArrayLayout: Columnar
X-Toon-Option-ByteArrayFormat: NumericArray
X-Toon-Option-KeyFolding: off
X-Toon-Option-Delimiter: COMMA

This overlay is applied only for the current response and does not change the application's registered ToonServiceOptions.

ByteArrayFormat is useful when a response should keep compact Base64 output by default but allow callers to opt into JSON-like numeric arrays for byte[] members:

GET /files/42
Accept: application/toon
X-Toon-Option-ByteArrayFormat: NumericArray

See Documentation/PerRequestEncodeOptions.md for details.

Package Notes

DevOp.Toon.API depends on DevOp.Toon for the runtime TOON implementation.