Ktor includes a multiplatform asynchronous HTTP client, which allows you to make requests and handle responses, extend its functionality with plugins (formerly known as features), such as authentication, JSON serialization, and so on. In this topic, we'll take an overview of the client - from setting it up to making requests and installing plugins.
To use the Ktor HTTP client in your project, you need to add at least two dependencies: a client dependency and an engine dependency. If you want to extend the client functionality with specific plugins, you also need to add the appropriate dependencies.
The main client functionality is available in the
ktor-client-core artifact. Depending on your build system, you can add it in the following way:
An engine is responsible for processing network requests. There are different client engines available for various platforms, such as Apache, CIO, Android, iOS, and so on. For example, you can add a
CIO engine dependency as follows:
For a full list of dependencies required for a specific engine, see Add an engine dependency.
If you want to use additional client plugins, you need to add a corresponding dependency. You can learn which dependencies you need from a topic for a required plugin.
Create the client
To instantiate the client, create the HttpClient class instance and pass an engine as a parameter:
In this example, we use the CIO engine.
You can also omit an engine:
In this case, the client will choose an engine automatically depending on the artifacts added in a build script. You can learn how the client chooses an engine from the Default engine documentation section.
Configure the client
To configure the client, you can pass an additional functional parameter to the client constructor. The HttpClientEngineConfig class is a base class for configuring the client. For instance, we can change the behaviour of exceptions as follows:
You can configure an engine using the
See the Engines section for additional details.
Ktor lets you use additional client functionality (plugins, formerly known as features) that is not available by default, for example, logging, authorization, or serialization. Most of them are provided in separate artifacts. For example, you can log HTTP calls by installing the Logging plugin:
You can also configure a plugin inside the
install block. For example, for the Logging plugin, you can specify the logger and logging level:
Make a request
The main way for making HTTP requests is the request function that takes a URL as a parameter. Inside this function, you can configure various request parameters: specify an HTTP method, add headers, specify the request body, and so on. These parameters are exposed by the HttpRequestBuilder class.
Note that this function allows you to receive a response in various ways. In this example, we receive a response as an
When calling the
request function, you can specify the desired HTTP method using the
In addition to the
HttpClient provides specific functions for basic HTTP methods:
put, and so on. For example, you can replace the example above with the following code:
To learn how to add headers, cookies, and specify a request body, see the Making requests help topic.
Receive a response
All functions used to make an HTTP request (
post, etc.) allow you to receive a response as an HttpResponse object.
HttpResponse exposes 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, headers, and so on. For example, you can receive a body as ByteArray as follows:
You can learn more from the Receiving responses topic.
Close the HTTP client
After you finish working with the HTTP client, you need to free up the resources: threads, connections, and
CoroutineScope for coroutines. To do this, call the
If you need to use
HttpClient for a single request, call the
use function, which automatically calls
close after executing the code block:
Note that the
close function prohibits creating new requests but doesn't terminate currently active ones. Resources will only be released after all client requests are completed.