JSON serialization plugin for Ktor HTTP client (JVM platform)
—
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.
Main plugin implementation that intercepts HTTP requests and responses to provide automatic JSON handling.
/**
* HttpClient plugin that serializes/de-serializes custom objects
* to request and from response bodies using a serializer.
*/
@Deprecated("Please use ContentNegotiation plugin")
class JsonPlugin internal constructor(
val serializer: JsonSerializer,
val acceptContentTypes: List<ContentType> = listOf(ContentType.Application.Json),
private val receiveContentTypeMatchers: List<ContentTypeMatcher> = listOf(JsonContentTypeMatcher()),
private val ignoredTypes: Set<KClass<*>> = DefaultCommonIgnoredTypes + DefaultIgnoredTypes
) {
/**
* Check if the plugin can handle the given content type
*/
internal fun canHandle(contentType: ContentType): Boolean
companion object Plugin : HttpClientPlugin<Config, JsonPlugin> {
override val key: AttributeKey<JsonPlugin>
override fun prepare(block: Config.() -> Unit): JsonPlugin
override fun install(plugin: JsonPlugin, scope: HttpClient)
}
}DSL configuration builder for customizing JSON plugin behavior.
/**
* JsonPlugin configuration that is used during installation
*/
@KtorDsl
class Config {
/**
* Serializer that will be used for serializing requests and deserializing response bodies.
* Default value is platform-specific defaultSerializer.
*/
var serializer: JsonSerializer?
/**
* List of content types that are handled by this plugin.
* It also affects Accept request header value.
*/
var acceptContentTypes: List<ContentType>
/**
* List of content type matchers that are handled by this plugin.
*/
var receiveContentTypeMatchers: List<ContentTypeMatcher>
/**
* Adds accepted content types. Existing content types will not be removed.
*/
fun accept(vararg contentTypes: ContentType)
/**
* Adds accepted content types. Existing content types will not be removed.
*/
fun receive(matcher: ContentTypeMatcher)
/**
* Adds a type to the list of types that should be ignored by JSON serialization.
* The list contains HttpStatusCode, ByteArray, String and streaming types by default.
*/
inline fun <reified T> ignoreType()
/**
* Adds a type to the list of types that should be ignored by JSON serialization.
*/
fun ignoreType(type: KClass<*>)
/**
* Remove T from the list of types that should be ignored by JSON serialization.
*/
inline fun <reified T> removeIgnoredType()
/**
* Remove type from the list of types that should be ignored by JSON serialization.
*/
fun removeIgnoredType(type: KClass<*>)
/**
* Clear all configured ignored types including defaults.
*/
fun clearIgnoredTypes()
}Convenient DSL function for installing the JSON plugin in HTTP client configuration.
/**
* Install JsonPlugin.
*/
@Deprecated("Please use ContentNegotiation plugin")
fun HttpClientConfig<*>.Json(block: JsonPlugin.Config.() -> Unit)Predefined sets of types that are ignored by JSON serialization.
internal val DefaultCommonIgnoredTypes: Set<KClass<*>>
internal expect val DefaultIgnoredTypes: Set<KClass<*>>import io.ktor.client.*
import io.ktor.client.plugins.json.*
val client = HttpClient {
install(JsonPlugin) {
// Uses platform default serializer
}
}val client = HttpClient {
install(JsonPlugin) {
accept(ContentType.Application.Json)
accept(ContentType("application", "vnd.api+json"))
// Custom content type matcher
receive(object : ContentTypeMatcher {
override fun contains(contentType: ContentType): Boolean {
return contentType.withoutParameters().toString().endsWith("+json")
}
})
}
}val client = HttpClient {
install(JsonPlugin) {
// Ignore custom types
ignoreType<MyStreamingType>()
ignoreType(MySpecialClass::class)
// Remove default ignored types if needed
removeIgnoredType<String>()
// Clear all ignored types (use with caution)
clearIgnoredTypes()
}
}val client = HttpClient {
install(JsonPlugin) {
acceptContentTypes = listOf(
ContentType.Application.Json,
ContentType("application", "hal+json"),
ContentType("application", "vnd.api+json")
)
}
}Install with Tessl CLI
npx tessl i tessl/maven-io-ktor--ktor-client-json-jvm