0
# Ktor Client Serialization
1

2
Ktor Client Serialization provides deprecated kotlinx.serialization support for Ktor HTTP client JSON plugin. This package offers the `KotlinxSerializer` class that enables automatic serialization and deserialization of Kotlin classes marked with `@Serializable` annotation when making HTTP requests and processing responses.
3

4
**⚠️ Deprecation Notice:** This package has been deprecated with ERROR level and replaced by the ContentNegotiation plugin which offers better performance and broader format support. New applications should use ContentNegotiation instead.
5

6
## Package Information
7

8
- **Package Name**: ktor-client-serialization-jvm
9
- **Package Type**: maven
10
- **Language**: Kotlin
11
- **Platform**: JVM (with multiplatform support)
12
- **Installation**: 
13
  ```kotlin
14
  implementation("io.ktor:ktor-client-serialization-jvm:3.2.0")
15
  ```
16

17
## Core Imports
18

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

25
## Basic Usage
26

27
```kotlin
28
import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
29
import io.ktor.client.plugins.json.*
30
import kotlinx.serialization.json.Json
31

32
// Create serializer with default configuration
33
val serializer = KotlinxSerializer()
34

35
// Create serializer with custom JSON configuration
36
val customJson = Json {
37
    isLenient = true
38
    ignoreUnknownKeys = true
39
}
40
val customSerializer = KotlinxSerializer(customJson)
41

42
// Use with Ktor HTTP client (deprecated pattern)
43
@Suppress("DEPRECATION_ERROR")
44
val client = HttpClient {
45
    install(JsonFeature) {
46
        serializer = KotlinxSerializer()
47
    }
48
}
49
```
50

51
## Capabilities
52

53
### KotlinxSerializer Class
54

55
Main serializer class implementing JsonSerializer interface for kotlinx.serialization integration.
56

57
```kotlin { .api }
58
@Deprecated(
59
    "Please use ContentNegotiation plugin and its converters",
60
    level = DeprecationLevel.ERROR
61
)
62
class KotlinxSerializer(
63
    private val json: Json = DefaultJson
64
) : JsonSerializer {
65
    
66
    /**
67
     * Serialize data to JSON content with specified content type
68
     */
69
    override fun write(data: Any, contentType: ContentType): OutgoingContent
70
    
71
    /**
72
     * Serialize data to JSON content with default JSON content type
73
     */
74
    fun write(data: Any): OutgoingContent
75
    
76
    /**
77
     * Deserialize JSON content to specified type using TypeInfo
78
     */
79
    override fun read(type: TypeInfo, body: Input): Any
80
    
81
    companion object {
82
        /**
83
         * Default Json configuration for KotlinxSerializer
84
         */
85
        val DefaultJson: Json
86
    }
87
}
88
```
89

90
### Write Methods
91

92
Serializes Kotlin objects to JSON content for HTTP requests.
93

94
```kotlin { .api }
95
/**
96
 * Serialize data to JSON content with specified content type
97
 * @param data - Any object to serialize (must be @Serializable)
98
 * @param contentType - HTTP content type for the output
99
 * @return OutgoingContent containing serialized JSON
100
 */
101
override fun write(data: Any, contentType: ContentType): OutgoingContent
102

103
/**
104
 * Serialize data to JSON content with default JSON content type (Application/Json)
105
 * @param data - Any object to serialize (must be @Serializable)
106
 * @return OutgoingContent containing serialized JSON
107
 */
108
fun write(data: Any): OutgoingContent
109
```
110

111
### Read Method
112

113
Deserializes JSON content from HTTP responses to Kotlin objects.
114

115
```kotlin { .api }
116
/**
117
 * Deserialize JSON content to specified type using TypeInfo
118
 * @param type - TypeInfo specifying the target type
119
 * @param body - Input stream containing JSON data
120
 * @return Deserialized object of the specified type
121
 */
122
override fun read(type: TypeInfo, body: Input): Any
123
```
124

125
### Default JSON Configuration
126

127
Default Json configuration used when no custom configuration is provided.
128

129
```kotlin { .api }
130
companion object {
131
    /**
132
     * Default Json configuration for KotlinxSerializer with conservative settings:
133
     * - isLenient = false
134
     * - ignoreUnknownKeys = false  
135
     * - allowSpecialFloatingPointValues = true
136
     * - useArrayPolymorphism = false
137
     */
138
    val DefaultJson: Json
139
}
140
```
141

142
## Types
143

144
### Required Types from Dependencies
145

146
```kotlin { .api }
147
// From kotlinx.serialization
148
interface Json {
149
    val serializersModule: SerializersModule
150
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
151
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
152
}
153

154
// From Ktor
155
interface JsonSerializer {
156
    fun write(data: Any, contentType: ContentType): OutgoingContent
157
    fun write(data: Any): OutgoingContent  // Default implementation delegates to write(data, ContentType.Application.Json)
158
    fun read(type: TypeInfo, body: Input): Any
159
}
160

161
interface ContentType
162
interface OutgoingContent
163
interface TypeInfo
164
interface Input
165
```
166

167
## Supported Data Types
168

169
The serializer automatically handles the following types through kotlinx.serialization:
170

171
- **Primitive types**: String, Int, Long, Float, Double, Boolean
172
- **Collections**: List, Set, Array, Map
173
- **@Serializable classes**: Custom Kotlin classes marked with @Serializable
174
- **JsonElement**: Direct JSON manipulation
175
- **Nullable types**: Optional values with null support
176

177
## Platform Support
178

179
This package supports multiple Kotlin platforms:
180

181
- **JVM**: Primary target platform 
182
- **JS**: JavaScript/Node.js environments
183
- **Native**: Native platforms (posix)
184
- **WebAssembly**: wasmJs target
185

186
Platform-specific initializers automatically register the serializer with the appropriate plugin system on each platform.
187

188
## Migration Path
189

190
**Instead of this deprecated package, use:**
191

192
```kotlin
193
// New approach with ContentNegotiation
194
import io.ktor.client.*
195
import io.ktor.client.plugins.contentnegotiation.*
196
import io.ktor.serialization.kotlinx.json.*
197

198
val client = HttpClient {
199
    install(ContentNegotiation) {
200
        json()
201
    }
202
}
203
```
204

205
The ContentNegotiation plugin provides:
206
- Better performance
207
- More serialization formats (JSON, XML, CBOR, ProtoBuf)
208
- Improved type safety
209
- Better error handling
210
- More flexible configuration options