Content negotiation and serialization
The ContentNegotiation plugin serves two primary purposes:
Negotiating media types between the client and server. For this, it uses the
Accept
andContent-Type
headers.Serializing/deserializing the content in a specific format when sending requests and receiving responses. Ktor supports the following formats out-of-the-box: JSON, XML, CBOR, and ProtoBuf. Note that the XML serializer is supported on JVM only.
Add dependencies
ContentNegotiation
To use ContentNegotiation
, you need to include the ktor-client-content-negotiation
artifact in the build script:
You can learn more about artifacts required by the Ktor client from Adding client dependencies.
Note that serializers for specific formats require additional artifacts. For example, kotlinx.serialization requires the ktor-serialization-kotlinx-json
dependency for JSON. Depending on the included artifacts, Ktor chooses a default serializer automatically. If required, you can specify the serializer explicitly and configure it.
Serialization
Before using kotlinx.serialization converters, you need to add the Kotlin serialization plugin as described in the Setup section.
JSON
To serialize/deserialize JSON data, you can choose one of the following libraries: kotlinx.serialization, Gson, or Jackson.
Add the ktor-serialization-kotlinx-json
artifact in the build script:
Add the ktor-serialization-gson
artifact in the build script:
Add the ktor-serialization-jackson
artifact in the build script:
XML
To serialize/deserialize XML, add the ktor-serialization-kotlinx-xml
in the build script:
Note that XML serialization is supported on JVM only.
CBOR
To serialize/deserialize CBOR, add the ktor-serialization-kotlinx-cbor
in the build script:
ProtoBuf
To serialize/deserialize ProtoBuf, add the ktor-serialization-kotlinx-protobuf
in the build script:
Install ContentNegotiation
To install ContentNegotiation
, pass it to the install
function inside a client configuration block:
Now you can configure the required JSON serializer.
Configure a serializer
JSON serializer
To register the JSON serializer in your application, call the json
method:
In the json
constructor, you can access the JsonBuilder API, for example:
You can find the full example here: client-json-kotlinx.
To register the Gson serializer in your application, call the gson method:
The gson
method also allows you to adjust serialization settings provided by GsonBuilder.
To register the Jackson serializer in your application, call the jackson method:
The jackson
method also allows you to adjust serialization settings provided by ObjectMapper.
XML serializer
To register the XML serializer in your application, call the xml
method:
The xml
method also allows you to access XML serialization settings, for example:
CBOR serializer
To register the CBOR serializer in your application, call the cbor
method:
The cbor
method also allows you to access CBOR serialization settings provided by CborBuilder, for example:
ProtoBuf serializer
To register the ProtoBuf serializer in your application, call the protobuf
method:
The protobuf
method also allows you to access ProtoBuf serialization settings provided by ProtoBufBuilder, for example:
Receive and send data
Create a data class
To receive and send data, you need to have a data class, for example:
If you use kotlinx.serialization, make sure that this class has the @Serializable
annotation:
Serializing/deserializing of the following types is supported by the kotlinx.serialization library:
Send data
To send a class instance within a request body as JSON, assign this instance using setBody
function and set the content type to application/json
by calling contentType
:
To send data as XML or CBOR, set contentType
to ContentType.Application.Xml
or ContentType.Application.Cbor
, respectively.
Receive data
When a server sends a response with the application/json
, application/xml
, or application/cbor
content, you can deserialize it by specifying a data class as a parameter of a function used to receive a response payload (body
in the example below):
You can find the full example here: client-json-kotlinx.