0
# Ktor Client Content Negotiation
1

2
Ktor client Content Negotiation plugin that provides automatic serialization and deserialization of request and response body content using various serialization formats like JSON, XML, and ProtoBuf. It handles content type negotiation by automatically setting Accept headers based on configured converters, processes incoming response content based on Content-Type headers, and provides extensible architecture for custom content converters.
3

4
## Package Information
5

6
- **Package Name**: ktor-client-content-negotiation-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  ```kotlin
11
  implementation("io.ktor:ktor-client-content-negotiation:3.2.0")
12
  ```
13

14
## Core Imports
15

16
```kotlin
17
import io.ktor.client.plugins.contentnegotiation.*
18
import io.ktor.serialization.*
19
import io.ktor.http.*
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.ktor.client.*
26
import io.ktor.client.plugins.contentnegotiation.*
27
import io.ktor.serialization.kotlinx.json.*
28

29
val client = HttpClient {
30
    install(ContentNegotiation) {
31
        json() // Install JSON converter
32
    }
33
}
34

35
// Automatic serialization on request
36
val response = client.post("https://api.example.com/users") {
37
    setBody(User(name = "Alice", email = "alice@example.com"))
38
}
39

40
// Automatic deserialization on response
41
val user: User = client.get("https://api.example.com/users/1").body()
42
```
43

44
## Architecture
45

46
The ContentNegotiation plugin is built around several key components:
47

48
- **Plugin Configuration**: `ContentNegotiationConfig` class for registering converters and configuring behavior
49
- **Content Converters**: `ContentConverter` interface implementations for specific serialization formats
50
- **Content Type Matching**: `ContentTypeMatcher` interface for flexible content type matching
51
- **Type Filtering**: Configurable ignored types that bypass content negotiation
52
- **Request/Response Transformation**: Automatic handling of Accept headers and content serialization/deserialization
53

54
## Capabilities
55

56
### Plugin Installation and Configuration
57

58
Install and configure the ContentNegotiation plugin with custom converters and settings.
59

60
```kotlin { .api }
61
val ContentNegotiation: ClientPlugin<ContentNegotiationConfig>
62

63
@KtorDsl
64
class ContentNegotiationConfig : Configuration {
65
    var defaultAcceptHeaderQValue: Double?
66
    
67
    override fun <T : ContentConverter> register(
68
        contentType: ContentType,
69
        converter: T,
70
        configuration: T.() -> Unit
71
    )
72
    
73
    fun <T : ContentConverter> register(
74
        contentTypeToSend: ContentType,
75
        converter: T,
76
        contentTypeMatcher: ContentTypeMatcher,
77
        configuration: T.() -> Unit
78
    )
79
    
80
    inline fun <reified T> ignoreType()
81
    fun ignoreType(type: KClass<*>)
82
    inline fun <reified T> removeIgnoredType()
83
    fun removeIgnoredType(type: KClass<*>)
84
    fun clearIgnoredTypes()
85
}
86
```
87

88
**Usage Examples:**
89

90
```kotlin
91
val client = HttpClient {
92
    install(ContentNegotiation) {
93
        // Register JSON converter
94
        json()
95
        
96
        // Register custom converter
97
        register(ContentType.Application.Xml, XmlConverter()) {
98
            // Configure converter
99
        }
100
        
101
        // Set Accept header quality value
102
        defaultAcceptHeaderQValue = 0.8
103
        
104
        // Ignore specific types
105
        ignoreType<String>()
106
        removeIgnoredType<ByteArray>()
107
    }
108
}
109
```
110

111
### Content Type Matching
112

113
Flexible content type matching for JSON and custom formats.
114

115
```kotlin { .api }
116
/**
117
 * Matcher that accepts all extended json content types
118
 */
119
object JsonContentTypeMatcher : ContentTypeMatcher {
120
    override fun contains(contentType: ContentType): Boolean {
121
        if (contentType.match(ContentType.Application.Json)) {
122
            return true
123
        }
124
        val value = contentType.withoutParameters().toString()
125
        return value in ContentType.Application && value.endsWith("+json", ignoreCase = true)
126
    }
127
}
128

129
/**
130
 * Interface for any objects that can match a ContentType.
131
 */
132
interface ContentTypeMatcher {
133
    /**
134
     * Checks if this type matches a contentType type.
135
     */
136
    fun contains(contentType: ContentType): Boolean
137
}
138
```
139

140
**Usage Examples:**
141

142
```kotlin
143
// Use built-in JSON matcher for extended JSON types
144
install(ContentNegotiation) {
145
    register(
146
        contentTypeToSend = ContentType.Application.Json,
147
        converter = JsonConverter(),
148
        contentTypeMatcher = JsonContentTypeMatcher
149
    )
150
}
151

152
// Create custom matcher
153
val customMatcher = object : ContentTypeMatcher {
154
    override fun contains(contentType: ContentType): Boolean {
155
        return contentType.match(ContentType.Application.Any) && 
156
               contentType.toString().endsWith("+custom")
157
    }
158
}
159
```
160

161
### Content Conversion
162

163
Core interfaces for implementing custom content converters.
164

165
```kotlin { .api }
166
/**
167
 * A custom content converter that could be registered in ContentNegotiation plugin
168
 * for any particular content type. Could provide bi-directional conversion implementation.
169
 * One of the most typical examples is a JSON content converter that provides both
170
 * serialization and deserialization.
171
 */
172
interface ContentConverter {
173
    /**
174
     * Serializes a [value] to the specified [contentType] to a [OutgoingContent].
175
     * This function could ignore value if it is not suitable for conversion and return `null`
176
     * so in this case other registered converters could be tried.
177
     *
178
     * @param charset response charset
179
     * @param typeInfo response body typeInfo
180
     * @param contentType to which this data converter has been registered
181
     * @param value to be converted
182
     * @return a converted [OutgoingContent] value, or null if [value] isn't suitable
183
     */
184
    suspend fun serialize(
185
        contentType: ContentType,
186
        charset: Charset,
187
        typeInfo: TypeInfo,
188
        value: Any?
189
    ): OutgoingContent?
190
    
191
    /**
192
     * Deserializes [content] to the value of type [typeInfo]
193
     * @return a converted value (deserialized) or `null` if not suitable for this converter
194
     */
195
    suspend fun deserialize(
196
        charset: Charset,
197
        typeInfo: TypeInfo,
198
        content: ByteReadChannel
199
    ): Any?
200
}
201

202
/**
203
 * Configuration for client and server ContentNegotiation plugin
204
 */
205
interface Configuration {
206
    fun <T : ContentConverter> register(
207
        contentType: ContentType,
208
        converter: T,
209
        configuration: T.() -> Unit = {}
210
    )
211
}
212
```
213

214
**Usage Examples:**
215

216
```kotlin
217
class CustomConverter : ContentConverter {
218
    override suspend fun serialize(
219
        contentType: ContentType,
220
        charset: Charset,
221
        typeInfo: TypeInfo,
222
        value: Any?
223
    ): OutgoingContent? {
224
        return when (value) {
225
            is MyCustomType -> TextContent(
226
                value.serialize(),
227
                contentType.withCharset(charset)
228
            )
229
            else -> null
230
        }
231
    }
232
    
233
    override suspend fun deserialize(
234
        charset: Charset,
235
        typeInfo: TypeInfo,
236
        content: ByteReadChannel
237
    ): Any? {
238
        if (typeInfo.type == MyCustomType::class) {
239
            val text = content.readUTF8Line()
240
            return MyCustomType.deserialize(text)
241
        }
242
        return null
243
    }
244
}
245
```
246

247
### Request-specific Content Type Exclusion
248

249
Exclude specific content types from Accept headers on a per-request basis.
250

251
```kotlin { .api }
252
fun HttpRequestBuilder.exclude(vararg contentType: ContentType)
253
```
254

255
**Usage Examples:**
256

257
```kotlin
258
// Exclude JSON from a specific request
259
val response = client.get("https://api.example.com/data") {
260
    exclude(ContentType.Application.Json)
261
}
262

263
// Exclude multiple content types
264
client.post("https://api.example.com/upload") {
265
    exclude(ContentType.Application.Json, ContentType.Application.Xml)
266
    setBody(rawData)
267
}
268
```
269

270
### Error Handling
271

272
Handle content conversion errors with detailed exception information.
273

274
```kotlin { .api }
275
/**
276
 * Base exception for content conversion errors
277
 */
278
open class ContentConvertException(
279
    message: String,
280
    cause: Throwable? = null
281
) : Exception(message, cause)
282

283
/**
284
 * JSON-specific conversion exception
285
 */
286
class JsonConvertException(
287
    message: String,
288
    cause: Throwable? = null
289
) : ContentConvertException(message, cause)
290

291
/**
292
 * Exception for content conversion failures specific to ContentNegotiation plugin
293
 */
294
class ContentConverterException(message: String) : Exception(message)
295
```
296

297
**Usage Examples:**
298

299
```kotlin
300
try {
301
    val result: MyType = client.get("https://api.example.com/data").body()
302
} catch (e: JsonConvertException) {
303
    println("JSON conversion failed: ${e.message}")
304
    // Handle JSON-specific error
305
} catch (e: ContentConvertException) {
306
    println("Content conversion failed: ${e.message}")
307
    // Handle general content conversion error
308
} catch (e: ContentConverterException) {
309
    println("ContentNegotiation plugin error: ${e.message}")
310
    // Handle plugin-specific error
311
}
312
```
313

314
### Utility Functions
315

316
Helper functions for charset detection and content processing.
317

318
```kotlin { .api }
319
/**
320
 * Detect suitable charset for an application call by Accept header or fallback to defaultCharset
321
 */
322
fun Headers.suitableCharset(defaultCharset: Charset = Charsets.UTF_8): Charset
323

324
/**
325
 * Detect suitable charset for an application call by Accept header or fallback to null
326
 */
327
fun Headers.suitableCharsetOrNull(defaultCharset: Charset = Charsets.UTF_8): Charset?
328
```
329

330
**Usage Examples:**
331

332
```kotlin
333
// In a custom converter
334
override suspend fun deserialize(
335
    charset: Charset,
336
    typeInfo: TypeInfo,
337
    content: ByteReadChannel
338
): Any? {
339
    val headers = /* get headers from context */
340
    val detectedCharset = headers.suitableCharset(Charsets.UTF_8)
341
    // Use detected charset for processing
342
}
343
```
344

345
## Types
346

347
```kotlin { .api }
348
// Core plugin type
349
val ContentNegotiation: ClientPlugin<ContentNegotiationConfig>
350

351
// Configuration class
352
@KtorDsl
353
class ContentNegotiationConfig : Configuration {
354
    var defaultAcceptHeaderQValue: Double?
355
}
356

357
// JSON content type matcher
358
object JsonContentTypeMatcher : ContentTypeMatcher
359

360
// Exception classes for conversion failures
361
open class ContentConvertException(message: String, cause: Throwable? = null) : Exception
362
class JsonConvertException(message: String, cause: Throwable? = null) : ContentConvertException
363
class ContentConverterException(message: String) : Exception
364

365
// Extension function for request exclusion
366
fun HttpRequestBuilder.exclude(vararg contentType: ContentType)
367

368
// Utility functions for charset handling
369
fun Headers.suitableCharset(defaultCharset: Charset = Charsets.UTF_8): Charset
370
fun Headers.suitableCharsetOrNull(defaultCharset: Charset = Charsets.UTF_8): Charset?
371
```
372

373
## Default Ignored Types
374

375
By default, the following types are ignored and bypass content negotiation:
376

377
### Common (All Platforms)
378
- `ByteArray::class`
379
- `String::class`
380
- `HttpStatusCode::class`
381
- `ByteReadChannel::class`
382
- `OutgoingContent::class`
383

384
### Platform-Specific
385
- **JVM**: `InputStream::class`
386
- **JS/WASM**: No additional types
387
- **Native**: No additional types
388

389
## Integration with Serialization Libraries
390

391
The plugin integrates with various Ktor serialization libraries:
392

393
```kotlin
394
// JSON with kotlinx.serialization
395
install(ContentNegotiation) {
396
    json()
397
}
398

399
// JSON with custom configuration
400
install(ContentNegotiation) {
401
    json(Json {
402
        prettyPrint = true
403
        ignoreUnknownKeys = true
404
    })
405
}
406

407
// XML support
408
install(ContentNegotiation) {
409
    xml()
410
}
411

412
// Multiple formats
413
install(ContentNegotiation) {
414
    json()
415
    xml()
416
    cbor()
417
}
418
```