Skip to content

Latest commit

 

History

History
100 lines (76 loc) · 6.6 KB

requests.md

File metadata and controls

100 lines (76 loc) · 6.6 KB

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:

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 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:


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/com/example/Application.kt" 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/com/example/Application.kt" 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/com/example/UploadFile.kt" include-symbol="main"}


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)
    // ...
}




{type="tip"}


Raw payload {id="raw"}


If you need to access the raw body payload and parse it by yourself, you can use the following functions: