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.

kotlinx.serialization (Multiplatform)

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

Add the Kotlin serialization plugin, as described in the Setup section.
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>

Gson and Jackson (JVM)

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

implementation "io.ktor:ktor-client-gson:$ktor_version"

implementation("io.ktor:ktor-client-gson:$ktor_version")

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-client-gson</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>
                    
        

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.

kotlinx.serialization

To use kotlinx.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
                })
            }

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

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.

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:

import kotlinx.serialization.*

@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 to the body property and set the content type to application/json by calling contentType:

        val response: HttpResponse = client.post("http://localhost:8080/customer") {
            contentType(ContentType.Application.Json)
            body = Customer(3, "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: Customer = client.get("http://localhost:8080/customer/3")

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

Last modified: 11 May 2022