Sending responses

Ktor allows you to handle incoming requests and send responses inside route handlers. You can send different types of responses: plain text, HTML documents and templates, serialized data objects, and so on. For each response, you can also configure various response parameters, such as a content type, headers, and cookies.

Inside a route handler, the following API is available for working with responses:

A set of functions targeted for sending a specific content type, for example, call.respondText, call.respondHtml, and so on.
The call.respond function that allows you to send any data inside a response. For example, with the enabled ContentNegotiation plugin, you can send a data object serialized in a specific format.
The call.response property that returns the ApplicationResponse object providing access to response parameters and allowing you to set a status code, add headers, and configure cookies.
The call.respondRedirect provides the capability to add redirects.

Set response payload

Plain text

To send a plain text in a response, use the call.respondText function:

get("/") {
    call.respondText("Hello, world!")
}

HTML

Ktor provides two main ways to send HTML responses to a client:

By building HTML using Kotlin HTML DSL.
By using JVM template engines, such as Freemarker, Velocity, and so on.

To send HTML build using Kotlin DSL, use the call.respondHtml function:

    routing {
        get("/") {
            val name = "Ktor"
            call.respondHtml(HttpStatusCode.OK) {
                head {
                    title {
                        +name
                    }
                }
                body {
                    h1 {
                        +"Hello from $name!"
                    }
                }
            }

To send a template in a response, call the call.respond function with a specific content ...

        get("/index") {
            val sampleUser = User(1, "John")
            call.respond(FreeMarkerContent("index.ftl", mapOf("user" to sampleUser)))
        }

... or use an appropriate call.respondTemplate function:

get("/index") {
    val sampleUser = User(1, "John")
    call.respondTemplate("index.ftl", mapOf("user" to sampleUser))
}

You can learn more from the Templating help section.

Object

To enable serialization of data objects in Ktor, you need to install the ContentNegotiation plugin and register a required converter (for example, JSON). Then, you can use the call.respond function to pass a data object in a response:

        get("/customer/{id}") {
            val id = call.parameters["id"]
            val customer: Customer = customerStorage.find { it.id == id!!.toInt() }!!
            call.respond(customer)
        }

You can find the full example here: json-kotlinx.

File

To respond to a client with a contents of a file, use the call.respondFile function. A code sample below shows how to send a specified file in a response and make this file downloadable by adding the Content-Disposition header:

fun Application.main() {
    routing {
        get("/download") {
            val file = File("files/ktor_logo.png")
            call.response.header(
                HttpHeaders.ContentDisposition,
                ContentDisposition.Attachment.withParameter(ContentDisposition.Parameters.FileName, "ktor_logo.png")
                    .toString()
            )
            call.respondFile(file)
        }
    }
}

To learn how to run this sample, see download-file.

Raw payload

If you need to send the raw body payload, use the call.respondBytes function.

Set response parameters

Status code

To set a status code for a response, call ApplicationResponse.status. You can pass a predefined status code value ...

get("/") {
    call.response.status(HttpStatusCode.OK)
}

... or specify a custom status code:

get("/") {
    response.status(HttpStatusCode(418, "I'm a tea pot"))
}

Note that functions for sending a payload have overloads for specifying a status code.

Content type

With the installed ContentNegotiation plugin, Ktor chooses a content type for a response automatically. If required, you can specify a content type manually by passing a corresponding parameter. For example, the call.respondText function in a code snippet below accepts ContentType.Text.Plain as a parameter:

get("/") {
    call.respondText("Hello, world!", ContentType.Text.Plain, HttpStatusCode.OK)
}

Headers

There are several ways to send specific headers in a response:

Add a header to the ApplicationResponse.headers collection:
get("/") { call.response.headers.append(HttpHeaders.ETag, "7c876b7e") }
Call the ApplicationResponse.header function:
get("/") { call.response.header(HttpHeaders.ETag, "7c876b7e") }
Use functions dedicated to specifying concrete headers, for example, ApplicationResponse.etag, ApplicationResponse.link, and so on.
get("/") { call.response.etag("7c876b7e") }
To add a custom header, pass its name as a string value to any function mentioned above, for example:
get("/") { call.response.header("Custom-Header", "Some value") }

Cookies

To access cookies sent in a response, use the ApplicationResponse.cookies property:

get("/") {
    call.response.cookies.append("yummy_cookie", "choco")
}

Ktor also provides the capability to handle sessions using cookies. You can learn more from the Sessions section.

Redirects

To generate a redirection response, call the respondRedirect function:

get("/") {
    call.respondRedirect("/moved", permanent = true)
}

get("/moved") {
    call.respondText("Moved content")
}

Last modified: 11 May 2022