Receiving responses
All functions used to make an HTTP request (request
, get
, post
, etc.) allow you to receive a response as an HttpResponse
object.
HttpResponse
exposes the API required to get a response body in various ways (raw bytes, JSON objects, etc.) and obtain response parameters, such as a status code, content type, and headers. For example, you can receive HttpResponse
for a GET
request without parameters in the following way:
Receive response parameters
The HttpResponse
class allows you to get various response parameters, such as a status code, headers, HTTP version, and more.
Status code
To get the status code of a response, use the HttpResponse.status
property:
Headers
The HttpResponse.headers
property allows you to get a Headers map containing all response headers. Additionally, HttpResponse
exposes the following functions for receiving specific header values:
contentType
for theContent-Type
header valuecharset
for a charset from theContent-Type
header value.etag
for theE-Tag
header value.setCookie
for theSet-Cookie
header value.
Receive response body
Raw body
To receive a raw body of a response, call the body
function and pass the required type as a parameter. The code snippet below shows how to receive a raw body as a String
:
Similarly, you can get a body as a ByteArray
:
A runnable example below shows how to get a response as a ByteArray
and save it to a file:
The onDownload()
extension function in the example above is used to display download progress.
For non-streaming requests, the response body is automatically loaded and cached in memory, allowing repeated access. While this is efficient for small payloads, it may lead to high memory usage with large responses.
To handle large responses efficiently, use a streaming approach, which processes the response incrementally without saving it in memory.
JSON object
With the ContentNegotiation plugin installed, you can deserialize JSON data into a data class when receiving responses:
To learn more, see Receive and send data.
Multipart form data
When receiving a response that contains multipart form data, you can read its body as a MultiPartData
instance. This allows you to process form fields and files included in the response.
The example below demonstrates how to handle both text form fields and file uploads from a multipart response:
Form fields
PartData.FormItem
represents a form field, which values can be accessed through the value property:
File uploads
PartData.FileItem
represents a file item. You can handle file uploads as byte streams:
Resource cleanup
Once the form processing is complete, each part is disposed of using the .dispose()
function to free resources.
Streaming data
When you call the HttpResponse.body
function to get a body, Ktor processes a response in memory and returns a full response body. If you need to get chunks of a response sequentially instead of waiting for the entire response, use HttpStatement
with scoped execute block. A runnable example below shows how to receive a response content in chunks (byte packets) and save them in a file:
In this example, ByteReadChannel
is used to read data asynchronously. Using ByteReadChannel.readRemaining()
retrieves all available bytes in the channel, while Source.transferTo()
directly writes the data to the file, reducing unnecessary allocations.
To save a response body to a file without extra processing, you can use the ByteReadChannel.copyAndClose()
function instead: