0
# Ktor Client Serialization
1

2
Ktor Client Serialization provides Kotlinx Serialization support for the Ktor HTTP Client, enabling automatic JSON serialization and deserialization of data classes marked with `@Serializable` annotation. This package implements a deprecated JsonSerializer that was part of the legacy JSON plugin system.
3

4
**Note**: This package is deprecated with `DeprecationLevel.ERROR` and has been superseded by the ContentNegotiation plugin with kotlinx.serialization converters. Users should migrate to the modern ContentNegotiation approach.
5

6
## Package Information
7

8
- **Package Name**: ktor-client-serialization
9
- **Package Type**: maven
10
- **Language**: Kotlin (multiplatform)
11
- **Installation**: Add to `build.gradle.kts`:
12
  ```kotlin
13
  implementation("io.ktor:ktor-client-serialization:3.2.0")
14
  ```
15

16
## Core Imports
17

18
```kotlin
19
import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
20
import kotlinx.serialization.json.Json
21
```
22

23
## Basic Usage
24

25
```kotlin
26
import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
27
import kotlinx.serialization.Serializable
28
import kotlinx.serialization.json.Json
29

30
// Define a serializable data class
31
@Serializable
32
data class User(val name: String, val age: Int)
33

34
// Create serializer with default configuration
35
val serializer = KotlinxSerializer()
36

37
// Or with custom Json configuration
38
val customJson = Json {
39
    ignoreUnknownKeys = true
40
    isLenient = true
41
}
42
val customSerializer = KotlinxSerializer(customJson)
43

44
// Use with legacy JSON plugin (deprecated)
45
// HttpClient {
46
//     install(JsonFeature) {
47
//         serializer = KotlinxSerializer()
48
//     }
49
// }
50
```
51

52
## Architecture
53

54
The package is built around the following key components:
55

56
- **KotlinxSerializer**: Main serializer class implementing the JsonSerializer interface
57
- **Json Configuration**: Configurable JSON processing with kotlinx.serialization
58
- **Multiplatform Support**: Platform-specific initialization for JVM, JS, Native, and WebAssembly
59
- **Type Detection**: Automatic serialization strategy selection based on data types
60
- **Legacy Integration**: Compatibility with the deprecated JSON plugin system
61

62
## Capabilities
63

64
### JSON Serialization
65

66
The KotlinxSerializer class provides JSON serialization and deserialization capabilities for Kotlin data classes.
67

68
```kotlin { .api }
69
/**
70
 * A JsonSerializer implemented for kotlinx Serializable classes.
71
 * 
72
 * @deprecated Please use ContentNegotiation plugin and its converters
73
 */
74
@Deprecated(
75
    "Please use ContentNegotiation plugin and its converters: https://ktor.io/docs/migration-to-20x.html#serialization-client",
76
    level = DeprecationLevel.ERROR
77
)
78
class KotlinxSerializer(
79
    private val json: Json = DefaultJson
80
) : JsonSerializer {
81
    
82
    /**
83
     * Convert data object to OutgoingContent with specified content type.
84
     */
85
    fun write(data: Any, contentType: ContentType): OutgoingContent
86
    
87
    /**
88
     * Convert data object to OutgoingContent with default JSON content type.
89
     */
90
    fun write(data: Any): OutgoingContent
91
    
92
    /**
93
     * Read content from response using information specified in type.
94
     */
95
    fun read(type: TypeInfo, body: Input): Any
96
    
97
    
98
    companion object {
99
        /**
100
         * Default Json configuration for KotlinxSerializer.
101
         */
102
        val DefaultJson: Json
103
    }
104
}
105
```
106

107
**Usage Examples:**
108

109
```kotlin
110
import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
111
import io.ktor.http.ContentType
112
import io.ktor.util.reflect.typeInfo
113
import io.ktor.utils.io.core.ByteReadPacket
114
import kotlinx.serialization.Serializable
115

116
@Serializable
117
data class Person(val name: String, val email: String)
118

119
val serializer = KotlinxSerializer()
120

121
// Serialize data to OutgoingContent
122
val person = Person("Alice", "alice@example.com")
123
val content = serializer.write(person, ContentType.Application.Json)
124

125
// Deserialize from Input (using ktor Input type)
126
val jsonBytes = """{"name":"Bob","email":"bob@example.com"}""".toByteArray()
127
val jsonInput = ByteReadPacket(jsonBytes)
128
val deserializedPerson = serializer.read(typeInfo<Person>(), jsonInput) as Person
129
```
130

131
### Write Operations
132

133
Serializes Kotlin objects to JSON format as OutgoingContent.
134

135
```kotlin { .api }
136
/**
137
 * Convert data object to OutgoingContent with specified content type.
138
 * @param data The object to serialize
139
 * @param contentType The content type for the output
140
 * @return OutgoingContent containing the serialized JSON
141
 */
142
fun write(data: Any, contentType: ContentType): OutgoingContent
143
```
144

145
### Read Operations
146

147
Deserializes JSON content to Kotlin objects using type information.
148

149
```kotlin { .api }
150
/**
151
 * Read content from response using information specified in type.
152
 * @param type TypeInfo containing the target type information
153
 * @param body Input stream containing JSON data
154
 * @return Deserialized object of the specified type
155
 */
156
fun read(type: TypeInfo, body: Input): Any
157
```
158

159
### Default Configuration
160

161
Provides a default Json configuration optimized for Ktor client usage.
162

163
```kotlin { .api }
164
/**
165
 * Default Json configuration for KotlinxSerializer.
166
 */
167
val DefaultJson: Json
168
```
169

170
The default configuration includes:
171
- `isLenient = false` - Strict JSON parsing
172
- `ignoreUnknownKeys = false` - Fail on unknown properties
173
- `allowSpecialFloatingPointValues = true` - Support for NaN and Infinity
174
- `useArrayPolymorphism = false` - Use object-based polymorphic serialization
175

176
### Platform Initialization
177

178
Each platform provides automatic initialization for the serializer registry.
179

180
```kotlin { .api }
181
/**
182
 * Platform-specific eager initialization object that registers KotlinxSerializer.
183
 * Available on JS, POSIX (Native), and WebAssembly platforms.
184
 */
185
@OptIn(ExperimentalStdlibApi::class)
186
@InternalAPI
187
@EagerInitialization
188
object SerializerInitializer
189
```
190

191
The initialization ensures that KotlinxSerializer is automatically available in the platform-specific serializer stores/registries without manual registration.
192

193
## Types
194

195
```kotlin { .api }
196
/**
197
 * Base interface for JSON serializers in Ktor client.
198
 */
199
@Deprecated(
200
    "Please use ContentNegotiation plugin and its converters",
201
    level = DeprecationLevel.ERROR
202
)
203
interface JsonSerializer {
204
    fun write(data: Any, contentType: ContentType): OutgoingContent
205
    fun write(data: Any): OutgoingContent
206
    fun read(type: TypeInfo, body: Input): Any
207
}
208

209
/**
210
 * Content type for HTTP requests and responses.
211
 */
212
class ContentType {
213
    companion object {
214
        object Application {
215
            val Json: ContentType
216
        }
217
    }
218
}
219

220
/**
221
 * Type information for deserialization.
222
 */
223
class TypeInfo
224

225
/**
226
 * Input interface for reading data from ktor.utils.io.core.
227
 */
228
interface Input
229

230
/**
231
 * Content that can be sent in HTTP requests.
232
 */
233
interface OutgoingContent
234

235
/**
236
 * Kotlinx Serialization Json configuration.
237
 * From kotlinx.serialization.json package.
238
 */
239
class Json {
240
    val isLenient: Boolean
241
    val ignoreUnknownKeys: Boolean
242
    val allowSpecialFloatingPointValues: Boolean
243
    val useArrayPolymorphism: Boolean
244
    val serializersModule: SerializersModule
245
    
246
    companion object {
247
        operator fun invoke(builderAction: JsonBuilder.() -> Unit): Json
248
    }
249
}
250

251
/**
252
 * Kotlinx Serialization serializers module.
253
 */
254
class SerializersModule
255
```
256

257
## Supported Types
258

259
The serializer automatically handles:
260

261
- **@Serializable data classes**: Primary use case with full type safety
262
- **Collections**: List, Set, Array with element type detection
263
- **Maps**: Map<K,V> with serializable keys and values
264
- **Primitive types**: String, Int, Long, Float, Double, Boolean
265
- **JsonElement types**: Direct kotlinx.serialization JSON elements
266
- **Nullable types**: Optional values with proper null handling
267
- **Polymorphic types**: With proper serialization configuration
268

269
## Error Handling
270

271
The serializer may throw exceptions in the following cases:
272

273
- **SerializationException**: When serialization/deserialization fails due to incompatible data structures or missing @Serializable annotations
274
- **IllegalArgumentException**: When collections contain mixed element types. Actual error message: `"Serializing collections of different element types is not yet supported. Selected serializers: [list of serializer names]"`
275
- **JsonDecodingException**: When JSON parsing fails due to malformed JSON or invalid syntax
276
- **ClassCastException**: When type information doesn't match actual data during deserialization
277
- **Error**: For mixed collection element types that cannot be unified under a single serializer
278

279
## Migration Guide
280

281
This package is deprecated. Migrate to ContentNegotiation:
282

283
**Old approach (deprecated):**
284
```kotlin
285
HttpClient {
286
    install(JsonFeature) {
287
        serializer = KotlinxSerializer()
288
    }
289
}
290
```
291

292
**New approach (recommended):**
293
```kotlin
294
HttpClient {
295
    install(ContentNegotiation) {
296
        json(Json {
297
            ignoreUnknownKeys = true
298
        })
299
    }
300
}
301
```
302

303
For detailed migration instructions, see: https://ktor.io/docs/migration-to-20x.html#serialization-client
304

305
## Platform Support
306

307
- **JVM**: Full support with all Java serialization features
308
- **JavaScript**: Browser and Node.js compatibility via platform-specific initialization
309
- **Native**: POSIX platforms support through native serialization
310
- **WebAssembly**: WebAssembly JavaScript target support