CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-ktor--ktor-client-json-jvm

JSON serialization plugin for Ktor HTTP client (JVM platform)

Pending
Overview
Eval results
Files

json-plugin.mddocs/

JSON Plugin Configuration

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.

Capabilities

JsonPlugin Class

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)
    }
}

Configuration Class

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()
}

Installation Extension Function

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)

Default Ignored Types

Predefined sets of types that are ignored by JSON serialization.

internal val DefaultCommonIgnoredTypes: Set<KClass<*>>
internal expect val DefaultIgnoredTypes: Set<KClass<*>>

Usage Examples

Basic Plugin Installation

import io.ktor.client.*
import io.ktor.client.plugins.json.*

val client = HttpClient {
    install(JsonPlugin) {
        // Uses platform default serializer
    }
}

Custom Content Types

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")
            }
        })
    }
}

Type Filtering Configuration

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()
    }
}

Multiple Content Types

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

docs

gson-serializer.md

index.md

jackson-serializer.md

json-plugin.md

json-serializer.md

kotlinx-serializer.md

tile.json