Ktor ContentNegotiation with Kotlinx Serialization: Install, Configure, and Avoid Common Pitfalls

Why ContentNegotiation Is the First Step for JSON APIs

When you expose a REST endpoint in Ktor, you almost always want to accept JSON from the client and return JSON back. The ContentNegotiation plugin bridges the gap between raw HTTP bodies and Kotlin data classes using Kotlinx Serialization. It automatically looks at the Content-Type header, picks the right converter, and serializes/deserializes the request and response.

Getting Started: Dependency and Plugin Installation

First add the serialization dependency to your module:

implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.0")

Then register the plugin before any routes that need JSON:

import io.ktor.server.application.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.json.Json

fun Application.module() {
    install(ContentNegotiation) {
        json(Json {
            encodeDefaults = true
            ignoreUnknownKeys = true
        })
    }

    // Routes go after the plugin
    routing {
        post("/users") {
            val user = call.receive()
            call.respond(HttpStatusCode.Created, user)
        }
    }
}

Replace User with your own @Serializable data class. The json() block configures the underlying Json instance; you can tweak pretty printing, default values, or unknown key handling.

How It Works Under the Hood

• When a request hits a post route, Ktor reads the Content-Type header.
• If it matches a registered converter (e.g., application/json), the plugin calls call.receive<User>() which deserializes the body.
• When you call call.respond(User), the plugin serializes the object back to JSON and sets Content-Type: application/json on the response.
• If the header is missing or unsupported, Ktor automatically throws a 415 Unsupported Media Type.
• Deserialization errors (malformed JSON, missing required fields) result in a 400 Bad Request.

Common Mistakes and How to Avoid Them

1. Skipping the dependency: The plugin won’t compile without ktor-serialization-kotlinx-json. Verify your build.gradle.kts includes it.
2. Installing after routes: The plugin must be installed before any route that uses call.receive or call.respond with a serializable type.
3. Wrong content type: Clients must send Content-Type: application/json. If they send text/plain, you’ll get a 415. Test with a tool like curl -H "Content-Type: application/json" -d '{"name":"Alice"}' http://localhost:8080/users.
4. Ignoring exceptions: call.receive throws ContentTransformationException on bad input. If you want custom error messages, wrap it in a try/catch and return a friendly JSON response.
5. Using multipart/form-data with JSON converter: The plugin won’t handle file uploads. For multipart, use call.receiveMultipart() instead.
6. Assuming validation: The plugin only serializes/deserializes. If you need to enforce business rules, add explicit validation logic or a library such as kotlinx.validation.
7. Client/server mismatch: If you build a Ktor HTTP client that doesn’t install the same converter, the client may send application/json but the server will reject it with a 415. Ensure both sides share the same serialization configuration.

Limitations to Keep in Mind

Feature	Supported?	Notes
JSON (application/json)	✅	Default converter; add install(ContentNegotiation) { json() }
CBOR, Smile, Protobuf	✅ (with extra dependencies)	Add ktor-serialization-kotlinx-cbor, ktor-serialization-kotlinx-protobuf, etc.
Multipart/form-data	❌	Use call.receiveMultipart() instead.
Binary streams	❌	Handle manually with call.receiveChannel().
Schema generation/validation	❌	Integrate external tools if needed.

Practical Verification Checklist

• Run the server and POST a valid JSON body; expect 201 Created with the same payload.
• Send a request with Content-Type: text/plain; expect 415 Unsupported Media Type.
• Remove the json() configuration; POST with JSON again; expect 400 Bad Request due to missing converter.
• Test a malformed JSON body; verify you receive a 400 Bad Request and the error message mentions deserialization failure.

When to Use Alternative Approaches

If you need advanced validation, schema enforcement, or support for XML, consider:

• ktor-serialization-jackson for Jackson-based JSON with schema support.
• Custom ApplicationFeature that wraps serialization and validation logic.
• Using kotlinx.serialization with kotlinx.validation or Ktor Validation plugin.

Conclusion

The ContentNegotiation plugin with Kotlinx Serialization is a lightweight, coroutine-friendly solution for most JSON APIs in Ktor. Install the dependency, register the plugin early, and remember the limits—especially the lack of multipart handling and validation. With these practices, you’ll avoid the most common pitfalls and deliver a reliable, type-safe endpoint.