requests.md

Learn how to handle incoming requests inside route handlers: get request information, receive body contents, etc.

Ktor allows you to handle incoming requests and send responses inside route handlers. You can perform various actions when handling requests:

• Get request information, such as headers, cookies, and so on.
• Get path parameter values.
• Get parameters of a query string.
• Receive body contents, for example, data objects, form parameters, and files.

General request information {id="request_information"}

Inside a route handler, you can get access to a request using the call.request property. This returns the ApplicationRequest instance and provides access to various request parameters. For example, the code snippet below shows how to get a request URI:

routing {
    get("/") {
        val uri = call.request.uri
        call.respondText("Request uri: $uri")
    }
}

The call.respondText method is used to send a response back to the client.

The ApplicationRequest object allows you to get access to various request data, for example:

• Headers
  To access all request headers, use the ApplicationRequest.headers property. You can also get access to specific headers using dedicated extension functions, such as acceptEncoding, contentType, cacheControl, and so on.
• Cookies
  The ApplicationRequest.cookies property provides access to cookies related to a request. To learn how to handle sessions using cookies, see the Sessions section.
• Connection details
  Use the ApplicationRequest.local property to get access to connection details such as a host name, port, scheme, and so on.
• X-Forwarded- headers
  To get information about a request passed through an HTTP proxy or a load balancer, install the plugin and use the ApplicationRequest.origin property.

Path parameters {id="path_parameters"}

When handling requests, you can get access to path parameter values using the call.parameters property. For example, call.parameters["login"] in the code snippet below will return admin for the /user/admin path:

{src="snippets/_misc/RouteParameter.kt"}

Query parameters {id="query_parameters"}

To get access to parameters of a query string, you can use the ApplicationRequest.queryParameters property. For example, if a request is made to /products?price=asc, you can access the price query parameter in this way:

{src="snippets/_misc/QueryParameter.kt"}

You can also obtain the entire query string using the ApplicationRequest.queryString function.

Body contents {id="body_contents"}

This section shows how to receive body contents sent with POST, PUT, or PATCH.

Raw payload {id="raw"}

To access the raw body payload and parse it manually, use the ApplicationCall.receive function that accepts a type of payload to be received. Suppose you have the following HTTP request:

{src="snippets/post-raw-data/post.http" include-lines="1-4"}

You can receive the body of this request as an object of the specified type in one of the following ways:

• String

  To receive a request body as a String value, use call.receive<String>(). You can also use receiveText to achieve the same result:

  {src="snippets/post-raw-data/src/main/kotlin/com/example/Application.kt" include-lines="13-16"}

• ByteArray

  To receive the body of a request as a byte array, call call.receive<ByteArray>():

  {src="snippets/post-raw-data/src/main/kotlin/com/example/Application.kt" include-lines="18-22"}

• ByteReadChannel

  You can use call.receive<ByteReadChannel>() or receiveChannel to receive ByteReadChannel that enables asynchronous reading of byte sequences:

  {src="snippets/post-raw-data/src/main/kotlin/com/example/Application.kt" include-lines="23-27"}

  The sample below shows how to use ByteReadChannel to upload a file:

  {src="snippets/post-raw-data/src/main/kotlin/com/example/Application.kt" include-lines="29-33"}

You can find the full example here: post-raw-data.

Objects {id="objects"}

Ktor provides a ContentNegotiation plugin to negotiate the media type of request and deserialize content to an object of a required type. To receive and convert content for a request, call the ApplicationCall.receive function that accepts a data class as a parameter:

{src="snippets/json-kotlinx/src/main/kotlin/jsonkotlinx/Application.kt" include-lines="38-42"}

You can learn more from .

Form parameters {id="form_parameters"}

Ktor allows you to receive form parameters sent with both x-www-form-urlencoded and multipart/form-data types using the receiveParameters function. The example below shows an HTTP client POST request with form parameters passed in a body:

{src="snippets/post-form-parameters/post.http"}

You can obtain parameter values in code as follows:

{src="snippets/post-form-parameters/src/main/kotlin/formparameters/Application.kt" include-lines="12-16"}

You can find the full example here: post-form-parameters.

Multipart form data {id="form_data"}

If you need to receive a file sent as a part of a multipart request, call the receiveMultipart function and then loop over each part as required. In the example below, PartData.FileItem is used to receive a file as a byte stream.

{src="snippets/upload-file/src/main/kotlin/uploadfile/UploadFile.kt" include-lines="3-38"}

Learn how to run this sample from upload-file.

To determine the uploaded file size, you can get the Content-Length header value inside the post handler:

post("/upload") {
    val contentLength = call.request.header(HttpHeaders.ContentLength)
    // ...
}