Ktor 2.1.3 Help

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 and Content-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, and CBOR. 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:

implementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
implementation "io.ktor:ktor-client-content-negotiation:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-content-negotiation-jvm</artifactId> <version>${ktor_version}</version> </dependency>

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.

JSON

To serialize/deserialize JSON data, you can choose one of the following libraries: kotlinx.serialization, Gson, or Jackson.

  1. Add the Kotlin serialization plugin, as described in the Setup section.

  2. Add the ktor-serialization-kotlinx-json artifact in the build script:

    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
    implementation "io.ktor:ktor-serialization-kotlinx-json:$ktor_version"
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId> <version>${ktor_version}</version> </dependency>
  • Add the ktor-serialization-gson artifact in the build script:

    implementation("io.ktor:ktor-serialization-gson:$ktor_version")
    implementation "io.ktor:ktor-serialization-gson:$ktor_version"
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-gson-jvm</artifactId> <version>${ktor_version}</version> </dependency>
  • Add the ktor-serialization-jackson artifact in the build script:

    implementation("io.ktor:ktor-serialization-jackson:$ktor_version")
    implementation "io.ktor:ktor-serialization-jackson:$ktor_version"
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-jackson-jvm</artifactId> <version>${ktor_version}</version> </dependency>

XML

To serialize/deserialize XML, add the ktor-serialization-kotlinx-xml in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-xml:$ktor_version")
implementation "io.ktor:ktor-serialization-kotlinx-xml:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Note that XML serialization is not supported for the Native server.

CBOR

To serialize/deserialize CBOR, add the ktor-serialization-kotlinx-cbor in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-cbor:$ktor_version")
implementation "io.ktor:ktor-serialization-kotlinx-cbor:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Install ContentNegotiation

To install ContentNegotiation, pass it to the install function inside a client configuration block:

val client = HttpClient(CIO) { install(ContentNegotiation) }

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:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.kotlinx.json.* val client = HttpClient(CIO) { install(ContentNegotiation) { json() } }

In the json constructor, you can access the JsonBuilder API, for example:

val client = HttpClient(CIO) { install(ContentNegotiation) { json(Json { prettyPrint = true isLenient = true }) } }

You can find the full example here: client-json-kotlinx.

To register the Gson serializer in your application, call the gson method:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.gson.* val client = HttpClient(CIO) { install(ContentNegotiation) { gson() } }

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:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.jackson.* val client = HttpClient(CIO) { install(ContentNegotiation) { jackson() } }

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:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.kotlinx.xml.* val client = HttpClient(CIO) { install(ContentNegotiation) { xml() } }

The xml method also allows you to access XML serialization settings, for example:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.kotlinx.xml.* import nl.adaptivity.xmlutil.* import nl.adaptivity.xmlutil.serialization.* val client = HttpClient(CIO) { install(ContentNegotiation) { xml(format = XML { xmlDeclMode = XmlDeclMode.Charset }) } }

CBOR serializer

To register the CBOR serializer in your application, call the cbor method:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.kotlinx.cbor.* val client = HttpClient(CIO) { install(ContentNegotiation) { cbor() } }

The cbor method also allows you to access CBOR serialization settings provided by CborBuilder, for example:

import io.ktor.client.plugins.contentnegotiation.* import io.ktor.serialization.kotlinx.cbor.* import kotlinx.serialization.cbor.* val client = HttpClient(CIO) { install(ContentNegotiation) { cbor(Cbor { ignoreUnknownKeys = true }) } }

Receive and send data

Create a data class

To receive and send data, you need to have a data class, for example:

data class Customer(val id: Int, val firstName: String, val lastName: String)

If you use kotlinx.serialization, make sure that this class has the @Serializable annotation:

@Serializable data class Customer(val id: Int, val firstName: String, val lastName: String)

To learn more about kotlinx.serialization, see the Kotlin Serialization Guide.

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:

val response: HttpResponse = client.post("http://localhost:8080/customer") { contentType(ContentType.Application.Json) setBody(Customer(3, "Jet", "Brains")) }

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):

val customer: Customer = client.get("http://localhost:8080/customer/3").body()

You can find the full example here: client-json-kotlinx.

Last modified: 19 July 2022