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.
This approach loads the entire response into memory at once, which can be problematic for large files. To reduce memory usage, consider streaming the data in chunks.
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.
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: