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 that provides access to response parameters and allows you to set the 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:
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:
To send a template in a response, call the call.respond function with a specific content ...
... or use an appropriate call.respondTemplate function:
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:
You can find the full example here: json-kotlinx.
File
To respond to a client with a content of a file, you have two options:
For
File
resources, use the call.respondFile function.For
Path
resources, use thecall.respond()
function with the LocalPathContent class.
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:
Note that this sample has two plugins installed:
PartialContent enables the server to respond to requests with the
Range
header and send only a portion of content.AutoHeadResponse provides the ability to automatically respond to
HEAD
request for every route that has aGET
defined. This allows the client application to determine the file size by reading theContent-Length
header value.
For the full code 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 ...
... or specify a custom status code:
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:
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 configure cookies sent in a response, use the ApplicationResponse.cookies property:
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: