0
# JSON Plugin Configuration
1

2
Core plugin for enabling JSON serialization and deserialization in Ktor HTTP clients. Provides comprehensive configuration options for content type matching, serializer selection, and type filtering.
3

4
## Capabilities
5

6
### JsonPlugin Class
7

8
Main plugin implementation that intercepts HTTP requests and responses to provide automatic JSON handling.
9

10
```kotlin { .api }
11
/**
12
 * HttpClient plugin that serializes/de-serializes custom objects
13
 * to request and from response bodies using a serializer.
14
 */
15
@Deprecated("Please use ContentNegotiation plugin")
16
class JsonPlugin internal constructor(
17
    val serializer: JsonSerializer,
18
    val acceptContentTypes: List<ContentType> = listOf(ContentType.Application.Json),
19
    private val receiveContentTypeMatchers: List<ContentTypeMatcher> = listOf(JsonContentTypeMatcher()),
20
    private val ignoredTypes: Set<KClass<*>> = DefaultCommonIgnoredTypes + DefaultIgnoredTypes
21
) {
22
    /**
23
     * Check if the plugin can handle the given content type
24
     */
25
    internal fun canHandle(contentType: ContentType): Boolean
26
    
27
    companion object Plugin : HttpClientPlugin<Config, JsonPlugin> {
28
        override val key: AttributeKey<JsonPlugin>
29
        override fun prepare(block: Config.() -> Unit): JsonPlugin
30
        override fun install(plugin: JsonPlugin, scope: HttpClient)
31
    }
32
}
33
```
34

35
### Configuration Class
36

37
DSL configuration builder for customizing JSON plugin behavior.
38

39
```kotlin { .api }
40
/**
41
 * JsonPlugin configuration that is used during installation
42
 */
43
@KtorDsl
44
class Config {
45
    /**
46
     * Serializer that will be used for serializing requests and deserializing response bodies.
47
     * Default value is platform-specific defaultSerializer.
48
     */
49
    var serializer: JsonSerializer?
50
    
51
    /**
52
     * List of content types that are handled by this plugin.
53
     * It also affects Accept request header value.
54
     */
55
    var acceptContentTypes: List<ContentType>
56
    
57
    /**
58
     * List of content type matchers that are handled by this plugin.
59
     */
60
    var receiveContentTypeMatchers: List<ContentTypeMatcher>
61
    
62
    /**
63
     * Adds accepted content types. Existing content types will not be removed.
64
     */
65
    fun accept(vararg contentTypes: ContentType)
66
    
67
    /**
68
     * Adds accepted content types. Existing content types will not be removed.
69
     */
70
    fun receive(matcher: ContentTypeMatcher)
71
    
72
    /**
73
     * Adds a type to the list of types that should be ignored by JSON serialization.
74
     * The list contains HttpStatusCode, ByteArray, String and streaming types by default.
75
     */
76
    inline fun <reified T> ignoreType()
77
    
78
    /**
79
     * Adds a type to the list of types that should be ignored by JSON serialization.
80
     */
81
    fun ignoreType(type: KClass<*>)
82
    
83
    /**
84
     * Remove T from the list of types that should be ignored by JSON serialization.
85
     */
86
    inline fun <reified T> removeIgnoredType()
87
    
88
    /**
89
     * Remove type from the list of types that should be ignored by JSON serialization.
90
     */
91
    fun removeIgnoredType(type: KClass<*>)
92
    
93
    /**
94
     * Clear all configured ignored types including defaults.
95
     */
96
    fun clearIgnoredTypes()
97
}
98
```
99

100
### Installation Extension Function
101

102
Convenient DSL function for installing the JSON plugin in HTTP client configuration.
103

104
```kotlin { .api }
105
/**
106
 * Install JsonPlugin.
107
 */
108
@Deprecated("Please use ContentNegotiation plugin")
109
fun HttpClientConfig<*>.Json(block: JsonPlugin.Config.() -> Unit)
110
```
111

112
### Default Ignored Types
113

114
Predefined sets of types that are ignored by JSON serialization.
115

116
```kotlin { .api }
117
internal val DefaultCommonIgnoredTypes: Set<KClass<*>>
118
internal expect val DefaultIgnoredTypes: Set<KClass<*>>
119
```
120

121
## Usage Examples
122

123
### Basic Plugin Installation
124

125
```kotlin
126
import io.ktor.client.*
127
import io.ktor.client.plugins.json.*
128

129
val client = HttpClient {
130
    install(JsonPlugin) {
131
        // Uses platform default serializer
132
    }
133
}
134
```
135

136
### Custom Content Types
137

138
```kotlin
139
val client = HttpClient {
140
    install(JsonPlugin) {
141
        accept(ContentType.Application.Json)
142
        accept(ContentType("application", "vnd.api+json"))
143
        
144
        // Custom content type matcher
145
        receive(object : ContentTypeMatcher {
146
            override fun contains(contentType: ContentType): Boolean {
147
                return contentType.withoutParameters().toString().endsWith("+json")
148
            }
149
        })
150
    }
151
}
152
```
153

154
### Type Filtering Configuration
155

156
```kotlin
157
val client = HttpClient {
158
    install(JsonPlugin) {
159
        // Ignore custom types
160
        ignoreType<MyStreamingType>()
161
        ignoreType(MySpecialClass::class)
162
        
163
        // Remove default ignored types if needed
164
        removeIgnoredType<String>()
165
        
166
        // Clear all ignored types (use with caution)
167
        clearIgnoredTypes()
168
    }
169
}
170
```
171

172
### Multiple Content Types
173

174
```kotlin
175
val client = HttpClient {
176
    install(JsonPlugin) {
177
        acceptContentTypes = listOf(
178
            ContentType.Application.Json,
179
            ContentType("application", "hal+json"),
180
            ContentType("application", "vnd.api+json")
181
        )
182
    }
183
}
184
```