Request preferences

This guide explores how to customize server responses using the Prefer header, a powerful HTTP mechanism that lets you control how the server processes and formats your requests.

Prefer header

The Prefer header is a standardized HTTP header that enables clients to express their preferences for request handling. It follows a simple key-value format and can include multiple preferences separated by commas. For more details, refer to the HTTP specification and MDN documentation.

Basic syntax:

Prefer: key=value

Multiple preferences:

Prefer: key1=value1,key2=value2

RxInferServer acknowledges applied preferences by setting the PreferenceApplied headers. Any unrecognized preferences are safely ignored.

Serialization Preferences

RxInferServer offers flexible JSON serialization options through the Prefer header. These options allow you to control how your data is formatted in responses. For a comprehensive overview of serialization capabilities, see the Serialization guide.

Multi-dimensional Array Representation Format

The mdarray_repr preference controls how multi-dimensional arrays are structured in the response. This is particularly useful when working with matrices and tensors. For detailed information about available formats, see the Multi-dimensional Array Representation Format section.

Available options for mdarray_repr:

Examples

Here, how, as an example, a simple 2x2 matrix would change its representation depending on different preferences:

A = [1 2; 3 4]

2×2 Matrix{Int64}:
 1  2
 3  4

set_header(client, "Prefer", "mdarray_repr=dict")

A

Dict{String, Any} with 4 entries:
  "shape"    => Any[2, 2]
  "encoding" => "array_of_arrays"
  "data"     => Any[Any[1, 2], Any[3, 4]]
  "type"     => "mdarray"

set_header(client, "Prefer", "mdarray_repr=dict_type_and_shape")

A

Dict{String, Any} with 3 entries:
  "shape" => Any[2, 2]
  "data"  => Any[Any[1, 2], Any[3, 4]]
  "type"  => "mdarray"

set_header(client, "Prefer", "mdarray_repr=dict_shape")

A

Dict{String, Any} with 2 entries:
  "shape" => Any[2, 2]
  "data"  => Any[Any[1, 2], Any[3, 4]]

set_header(client, "Prefer", "mdarray_repr=data")

A

2-element Vector{Any}:
 Any[1, 2]
 Any[3, 4]

Multi-dimensional Array Data Encoding

The mdarray_data preference determines how array data is encoded in the response. This is crucial for optimizing data transfer and ensuring compatibility with different client implementations. For more details, see the Multi-dimensional Array Data Encoding section.

Available options for mdarray_data:

Examples

Here, how, as an example, a simple 2x2 matrix would change its representation depending on different preferences:

A = [1 2; 3 4]

2×2 Matrix{Int64}:
 1  2
 3  4

set_header(client, "Prefer", "mdarray_data=array_of_arrays")

A

Dict{String, Any} with 4 entries:
  "shape"    => Any[2, 2]
  "encoding" => "array_of_arrays"
  "data"     => Any[Any[1, 2], Any[3, 4]]
  "type"     => "mdarray"

set_header(client, "Prefer", "mdarray_data=reshape_column_major")

A

Dict{String, Any} with 4 entries:
  "shape"    => Any[2, 2]
  "encoding" => "reshape_column_major"
  "data"     => Any[1, 3, 2, 4]
  "type"     => "mdarray"

set_header(client, "Prefer", "mdarray_data=reshape_row_major")

A

Dict{String, Any} with 4 entries:
  "shape"    => Any[2, 2]
  "encoding" => "reshape_row_major"
  "data"     => Any[1, 2, 3, 4]
  "type"     => "mdarray"

set_header(client, "Prefer", "mdarray_data=diagonal")

A

Dict{String, Any} with 4 entries:
  "shape"    => Any[2, 2]
  "encoding" => "diagonal"
  "data"     => Any[1, 4]
  "type"     => "mdarray"

set_header(client, "Prefer", "mdarray_data=none")

It is possible to remove the matrices from the request entirely by setting the mdarray_data preference to none together with the mdarray_repr preference to data.

set_header(client, "Prefer", "mdarray_repr=data,mdarray_data=none")

A

Distribution Representation Format

The distributions_repr preference controls how probability distributions are structured in the response. This is particularly useful when working with statistical models. For detailed information about available formats, see the Distribution Representation Format section.

Available options for distributions_repr:

Examples

Here's how a normal distribution would change its representation depending on different preferences. We will show both the univariate and multivariate cases.

univariate_distribution = NormalMeanVariance(1.0, 2.0)

ExponentialFamily.NormalMeanVariance{Float64}(μ=1.0, v=2.0)

multivariate_distribution = MvNormalMeanCovariance([1.0, 2.0], [3.0 0.0; 0.0 4.0])

MvNormalMeanCovariance(
μ: [1.0, 2.0]
Σ: [3.0 0.0; 0.0 4.0]
)

set_header(client, "Prefer", "distributions_repr=dict")

univariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "NormalMeanVariance"
  "encoding" => "named_params"
  "data"     => Dict{String, Any}("v"=>2.0, "μ"=>1.0)
  "type"     => "Distribution{Univariate, Continuous}"

multivariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "MvNormalMeanCovariance"
  "encoding" => "named_params"
  "data"     => Dict{String, Any}("μ"=>Any[1.0, 2.0], "Σ"=>Dict{String, Any}("s…
  "type"     => "AbstractMvNormal"

set_header(client, "Prefer", "distributions_repr=dict_type_and_tag")

univariate_distribution

Dict{String, Any} with 3 entries:
  "tag"  => "NormalMeanVariance"
  "data" => Dict{String, Any}("v"=>2.0, "μ"=>1.0)
  "type" => "Distribution{Univariate, Continuous}"

multivariate_distribution

Dict{String, Any} with 3 entries:
  "tag"  => "MvNormalMeanCovariance"
  "data" => Dict{String, Any}("μ"=>Any[1.0, 2.0], "Σ"=>Dict{String, Any}("shape…
  "type" => "AbstractMvNormal"

set_header(client, "Prefer", "distributions_repr=dict_tag")

univariate_distribution

Dict{String, Any} with 2 entries:
  "tag"  => "NormalMeanVariance"
  "data" => Dict{String, Any}("v"=>2.0, "μ"=>1.0)

multivariate_distribution

Dict{String, Any} with 2 entries:
  "tag"  => "MvNormalMeanCovariance"
  "data" => Dict{String, Any}("μ"=>Any[1.0, 2.0], "Σ"=>Dict{String, Any}("shape…

set_header(client, "Prefer", "distributions_repr=data")

univariate_distribution

Dict{String, Any} with 2 entries:
  "v" => 2.0
  "μ" => 1.0

multivariate_distribution

Dict{String, Any} with 2 entries:
  "μ" => Any[1.0, 2.0]
  "Σ" => Dict{String, Any}("shape"=>Any[2, 2], "encoding"=>"array_of_arrays", "…

Distribution Data Encoding

The distributions_data preference determines how distribution parameters are encoded in the response. This is crucial for ensuring compatibility with different client implementations and providing consistent parameterization. For more details, see the Distribution Data Encoding section.

Available options for distributions_data:

Examples

Here's how different distributions would change their representation depending on different preferences:

set_header(client, "Prefer", "distributions_data=named_params")

univariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "NormalMeanVariance"
  "encoding" => "named_params"
  "data"     => Dict{String, Any}("v"=>2.0, "μ"=>1.0)
  "type"     => "Distribution{Univariate, Continuous}"

multivariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "MvNormalMeanCovariance"
  "encoding" => "named_params"
  "data"     => Dict{String, Any}("μ"=>Any[1.0, 2.0], "Σ"=>Dict{String, Any}("s…
  "type"     => "AbstractMvNormal"

set_header(client, "Prefer", "distributions_data=params")

univariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "NormalMeanVariance"
  "encoding" => "params"
  "data"     => Any[1.0, 2.0]
  "type"     => "Distribution{Univariate, Continuous}"

multivariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "MvNormalMeanCovariance"
  "encoding" => "params"
  "data"     => Any[Any[1.0, 2.0], Dict{String, Any}("shape"=>Any[2, 2], "encod…
  "type"     => "AbstractMvNormal"

set_header(client, "Prefer", "distributions_data=mean_cov")

univariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "NormalMeanVariance"
  "encoding" => "mean_cov"
  "data"     => Dict{String, Any}("mean"=>1.0, "cov"=>2.0)
  "type"     => "Distribution{Univariate, Continuous}"

multivariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "MvNormalMeanCovariance"
  "encoding" => "mean_cov"
  "data"     => Dict{String, Any}("mean"=>Any[1.0, 2.0], "cov"=>Dict{String, An…
  "type"     => "AbstractMvNormal"

set_header(client, "Prefer", "distributions_data=none")

univariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "NormalMeanVariance"
  "encoding" => "none"
  "data"     => nothing
  "type"     => "Distribution{Univariate, Continuous}"

multivariate_distribution

Dict{String, Any} with 4 entries:
  "tag"      => "MvNormalMeanCovariance"
  "encoding" => "none"
  "data"     => nothing
  "type"     => "AbstractMvNormal"

It is possible to combine multiple preferences to achieve the desired output format. For example, to get just the mean and covariance parameters in a compact format:

set_header(client, "Prefer", "distributions_repr=data,distributions_data=mean_cov")

univariate_distribution

Dict{String, Any} with 2 entries:
  "mean" => 1.0
  "cov"  => 2.0

multivariate_distribution

Dict{String, Any} with 2 entries:
  "mean" => Any[1.0, 2.0]
  "cov"  => Dict{String, Any}("shape"=>Any[2, 2], "encoding"=>"array_of_arrays"…

Combination of preferences

It is possible to combine multiple preferences to achieve the desired output format. For example, we could request server to return a diagonal part of the covariance matrix of a multivariate distribution without extra metadata in the following way:

set_header(client, "Prefer", "distributions_repr=data,distributions_data=mean_cov,mdarray_repr=data,mdarray_data=diagonal")

multivariate_distribution

Dict{String, Any} with 2 entries:
  "mean" => Any[1.0, 2.0]
  "cov"  => Any[3.0, 4.0]

API Reference

RequestPreferences(req::HTTP.Request)