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. Ktor supports the following formats out-of-the-box: JSON, XML, CBOR, and ProtoBuf.
Add dependencies
ContentNegotiation
To use ContentNegotiation
, you need to include the ktor-server-content-negotiation
artifact in the build script:
Note that serializers for specific formats require additional artifacts. For example, kotlinx.serialization requires the ktor-serialization-kotlinx-json
dependency for JSON.
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:
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 the ContentNegotiation
plugin to the application, pass it to the install
function in the specified module. The code snippets below show how to install ContentNegotiation
...
... inside the
embeddedServer
function call.... inside the explicitly defined
module
, which is an extension function of theApplication
class.
Configure a serializer
Ktor supports the following formats out-of-the-box: JSON, XML, CBOR. You can also implement your own custom serializer.
JSON serializer
To register the JSON serializer in your application, call the json
method:
The json
method also allows you to adjust serialization settings provided by JsonBuilder, for example:
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, for example:
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, for example:
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:
Custom serializer
To register a custom serializer for a specified Content-Type
, you need to call the register
method. In the example below, two custom serializer are registered to deserialize application/json
and application/xml
data:
Receive and send data
Create a data class
To deserialize received data into an object, you need to create 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:
Receive data
To receive and convert a content for a request, call the receive
method that accepts a data class as a parameter:
The Content-Type
of the request will be used to choose a serializer for processing the request. The example below shows a sample HTTP client request containing JSON or XML data that is converted to a Customer
object on the server side:
You can find the full example here: json-kotlinx.
Send data
To pass a data object in a response, you can use the respond
method:
In this case, Ktor uses the Accept
header to choose the required serializer. You can find the full example here: json-kotlinx.
Implement a custom serializer
In Ktor, you can write your own serializer for serializing/deserializing data. To do this, you need to implement the ContentConverter interface:
Take a look at the GsonConverter class as an implementation example.