WebSockets serialization

Similar to the ContentNegotiation plugin, WebSockets allow you to serialize/deserialize text frames in a specific format. The Ktor client supports the following formats out-of-the-box: JSON, XML, CBOR, and ProtoBuf.

Add dependencies

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:

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 supported on JVM only.

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>
                    
        

ProtoBuf

To serialize/deserialize ProtoBuf, add the ktor-serialization-kotlinx-protobuf in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-protobuf:$ktor_version")

implementation "io.ktor:ktor-serialization-kotlinx-protobuf:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Configure a serializer

JSON serializer

To register the JSON serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the Json parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*

val client = HttpClient(CIO) {
    install(WebSockets) {
        contentConverter = KotlinxWebsocketSerializationConverter(Json)
    }
}

To register the Gson serializer, assign GsonWebsocketContentConverter to the contentConverter property:

import io.ktor.serialization.gson.*

install(WebSockets) {
    contentConverter = GsonWebsocketContentConverter()
}

To register the Jackson serializer, assign JacksonWebsocketContentConverter to the contentConverter property:

import io.ktor.serialization.jackson.*

install(WebSockets) {
    contentConverter = JacksonWebsocketContentConverter()
}

XML serializer

To register the XML serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the XML parameter and assign this instance to the contentConverter property:

import nl.adaptivity.xmlutil.serialization.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(XML)
}

CBOR serializer

To register the CBOR serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the Cbor parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.cbor.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Cbor)
}

ProtoBuf serializer

To register the ProtoBuf serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the ProtoBuf parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.protobuf.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(ProtoBuf)
}

Receive and send data

Create a data class

To serialize/deserialize text frames into/from 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:

@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 text frame in a specified format, use the sendSerialized function:

        client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/customer") {
            sendSerialized(Customer(1, "Jane", "Smith"))
        }

Receive data

To receive and convert a content of a text frame, call the receiveDeserialized function that accepts a data class as a parameter:

        client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/customer/1") {
            val customer = receiveDeserialized<Customer>()
            println("A customer with id ${customer.id} is received by the client.")
        }

To receive deserialized frames from the incoming channel, use the WebsocketContentConverter.deserialize function. WebsocketContentConverter is available via the DefaultClientWebSocketSession.converter property.

Last modified: 02 April 2024