Ktor 1.5.0 Help

Json

JsonFeature can be used to serialize/deserialize JSON data when sending requests and receiving responses. This functionality is provided for JVM by using the Gson/Jackson libraries and for Kotlin Multiplatform by using kotlinx.serialization.

Add Dependencies

Before installing JsonFeature, you need to add a dependency for the desired serializer. If your project targets only JVM, you can add Gson or Jackson dependency. For multiplatform projects, use the kotlinx.serialization library. Depending on the included artifacts, Ktor chooses a default serializer automatically. If required, you can specify the serializer explicitly and configure it.

JVM: Gson and Jackson

To use Gson, add the following artifact to the build script:

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

For Jackson, add the following dependency:

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

JVM, iOS, JS: kotlinx

For multiplatform projects, you can use the kotlinx.serialization library. You can add it to the project as follows:

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

  2. Add the ktor-client-serialization dependency:

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

Install JsonFeature

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

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

Now you can configure the required JSON serializer.

Configure a Serializer

Depending on the included artifacts, Ktor chooses a default serializer automatically. You can get this serializer by calling the io.ktor.client.features.json.defaultSerializer function.

To specify the required serializer explicitly, use the serializer property:

install(JsonFeature) { serializer = KotlinxSerializer() }

For the selected serializer, you can access its API and adjust a configuration. Let's see how to do this.

Gson

To use Gson, assign the GsonSerializer instance to the serializer property:

install(JsonFeature) { serializer = GsonSerializer() }

Inside the GsonSerializer constructor, you can access GsonBuilder API, for example:

install(JsonFeature) { serializer = GsonSerializer() { setPrettyPrinting() disableHtmlEscaping() } }

Jackson

To use Jackson, assign the JacksonSerializer instance to the serializer property:

install(JsonFeature) { serializer = JacksonSerializer() }

Inside the JacksonSerializer constructor, you can access the ObjectMapper API...

install(JsonFeature) { serializer = JacksonSerializer() { enable(SerializationFeature.INDENT_OUTPUT) dateFormat = DateFormat.getDateInstance() } }

... or pass the ObjectMapper instance directly to the JacksonSerializer constructor.

kotlinx

To use Kotlin serialization, assign the KotlinxSerializer instance to the serializer property:

install(JsonFeature) { serializer = KotlinxSerializer() }

Inside the KotlinxSerializer constructor, you can access the JsonBuilder API, for example:

install(JsonFeature) { serializer = KotlinxSerializer(kotlinx.serialization.json.Json { prettyPrint = true isLenient = true }) }

Receive and Send Data

Create a Data Class

To deserialize received data into an object, you need to create 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:

import kotlinx.serialization.Serializable @Serializable data class Customer(val id: Int, val firstName: String, val lastName: String)

Send Data

To send a class instance within a request body as JSON, assign this instance to the body property and set the content type to application/json by calling contentType:

client.post<Unit>() { url("http://127.0.0.1:8080/customer") contentType(ContentType.Application.Json) body = Customer(1, "Jet", "Brains") }

Receive Data

When a server sends a response with the application/json content, you can deserialize it by specifying a data class as a parameter of the required request method, for example:

val customer = client.get<Customer>("http://127.0.0.1:8080/customer")
Last modified: 28 December 2020