or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

gson-serializer.mdindex.mdjackson-serializer.mdjson-plugin.mdjson-serializer.mdkotlinx-serializer.md
tile.json

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

JSON serialization plugin for Ktor HTTP client (JVM platform)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-json-jvm@2.3.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-json-jvm@2.3.0

index.mddocs/

Ktor Client JSON Plugin

The Ktor Client JSON plugin provides automatic JSON serialization and deserialization for HTTP client requests and responses. It supports multiple serialization backends including Gson, Jackson, and Kotlinx Serialization, with configurable content type matching and type filtering.

Note: This plugin is deprecated. Use the ContentNegotiation plugin for new projects.

Package Information

  • Package Name: io.ktor:ktor-client-json-jvm
  • Package Type: Maven/Gradle
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-client-json:2.3.13")

Core Imports

import io.ktor.client.plugins.json.*
import io.ktor.client.plugins.gson.*
import io.ktor.client.plugins.jackson.*
import io.ktor.client.plugins.kotlinx.serializer.*

Basic Usage

import io.ktor.client.*
import io.ktor.client.plugins.json.*
import io.ktor.client.plugins.gson.*
import io.ktor.client.request.*
import io.ktor.client.statement.*

// Install JSON plugin with default Gson serializer
val client = HttpClient {
    install(JsonPlugin) {
        serializer = GsonSerializer()
    }
}

// Using data classes for automatic serialization
@Serializable
data class User(val name: String, val email: String)

// POST request with automatic JSON serialization
val response: HttpResponse = client.post("https://api.example.com/users") {
    contentType(ContentType.Application.Json)
    setBody(User("Alice", "alice@example.com"))
}

// GET request with automatic JSON deserialization
val user: User = client.get("https://api.example.com/users/1").body()

Architecture

The Ktor Client JSON plugin is built around several key components:

  • JsonPlugin: Main plugin class that intercepts HTTP requests and responses
  • JsonSerializer Interface: Abstract serializer interface for different JSON backends
  • Gson Integration: GsonSerializer implementation using Google Gson
  • Jackson Integration: JacksonSerializer implementation using Jackson ObjectMapper
  • Kotlinx Serialization: KotlinxSerializer implementation using kotlinx.serialization
  • Content Type Matching: Flexible content type detection including +json variants
  • Type Filtering: Configurable type ignore lists to prevent unwanted serialization

Capabilities

JSON Plugin Installation

Core plugin configuration and installation for HTTP clients. Provides content type negotiation, serializer selection, and type filtering.

@Deprecated("Please use ContentNegotiation plugin")
class JsonPlugin internal constructor(
    val serializer: JsonSerializer,
    val acceptContentTypes: List<ContentType>,
    private val receiveContentTypeMatchers: List<ContentTypeMatcher>,
    private val ignoredTypes: Set<KClass<*>>
)

@KtorDsl
class Config {
    var serializer: JsonSerializer?
    var acceptContentTypes: List<ContentType>
    var receiveContentTypeMatchers: List<ContentTypeMatcher>
    
    fun accept(vararg contentTypes: ContentType)
    fun receive(matcher: ContentTypeMatcher)
    inline fun <reified T> ignoreType()
    fun ignoreType(type: KClass<*>)
    inline fun <reified T> removeIgnoredType()
    fun removeIgnoredType(type: KClass<*>)
    fun clearIgnoredTypes()
}

fun HttpClientConfig<*>.Json(block: JsonPlugin.Config.() -> Unit)

JSON Plugin Configuration

JSON Serialization Interface

Abstract serializer interface for implementing JSON backends. Defines the core serialization contract for request/response transformation.

@Deprecated("Please use ContentNegotiation plugin")
interface JsonSerializer {
    fun write(data: Any, contentType: ContentType): OutgoingContent
    fun write(data: Any): OutgoingContent
    fun read(type: TypeInfo, body: Input): Any
}

expect fun defaultSerializer(): JsonSerializer

JSON Serializer Interface

Gson Serialization

Google Gson-based JSON serialization implementation with configurable Gson builder support.

@Deprecated("Please use ContentNegotiation plugin")
class GsonSerializer(block: GsonBuilder.() -> Unit = {}) : JsonSerializer {
    override fun write(data: Any, contentType: ContentType): OutgoingContent
    override fun read(type: TypeInfo, body: Input): Any
}

Gson Serialization

Jackson Serialization

Jackson-based JSON serialization implementation with configurable ObjectMapper support and advanced data binding features.

@Deprecated("Please use ContentNegotiation plugin")
class JacksonSerializer(
    jackson: ObjectMapper = jacksonObjectMapper(),
    block: ObjectMapper.() -> Unit = {}
) : JsonSerializer {
    override fun write(data: Any, contentType: ContentType): OutgoingContent
    override fun read(type: TypeInfo, body: Input): Any
}

Jackson Serialization

Kotlinx Serialization

Kotlinx Serialization-based JSON implementation with configurable Json instance and advanced serialization features.

@Deprecated("Please use ContentNegotiation plugin")
class KotlinxSerializer(private val json: Json = DefaultJson) : JsonSerializer {
    override fun write(data: Any, contentType: ContentType): OutgoingContent
    override fun read(type: TypeInfo, body: Input): Any
    
    companion object {
        val DefaultJson: Json
    }
}

Kotlinx Serialization

Types

// Content type matching
interface ContentTypeMatcher {
    fun contains(contentType: ContentType): Boolean
}

// Type information for deserialization
expect class TypeInfo {
    val type: KClass<*>
    val reifiedType: Type
    val kotlinType: KType?
}

// HTTP content types
object ContentType {
    object Application {
        val Json: ContentType
    }
}

// Outgoing HTTP content
abstract class OutgoingContent
class TextContent(
    val text: String,
    val contentType: ContentType
) : OutgoingContent

// Input stream for reading response bodies
interface Input {
    fun readText(): String
}