Creating a client application

Ktor includes a multiplatform asynchronous HTTP client, which allows you to make requests and handle responses, extend its functionality with plugins, such as authentication, JSON serialization, and so on. In this tutorial, we'll create a simple client application for sending a request and receiving a response.

Prerequisites

Before starting this tutorial:

Install IntelliJ IDEA Community or Ultimate.
Make sure the Kotlin plugin is installed and enabled. Learn how to do this from the Install plugins topic.

Create a new project

To try out a Ktor client in action, we'll create a Kotlin/JVM project. Open IntelliJ IDEA, and follow the steps below:

On the Welcome screen, click New Project.
Otherwise, from the main menu, select File | New | Project.
In the New Project wizard, choose Kotlin Multiplatform from the list on the left.
On the right pane, specify the following settings:
- Name: Specify a project name.
- Location: Specify a directory for your project.
- Project Template: Choose Console Application in the JVM group.
- Build System: Make sure that Gradle Kotlin is selected.
Click Next.
On the next page, change Test framework to None, click Finish and wait until IntelliJ IDEA generates a project and installs the dependencies.

Add dependencies

Let's add dependencies required for a Ktor client.

Open the gradle.properties file and add the following line to specify the Ktor version:
ktor_version=2.3.1
To use the EAP version of Ktor, you need to add a Space repository.
Open the build.gradle.kts file and add the following artifacts to the dependencies block:
val ktor_version: String by project dependencies { implementation("io.ktor:ktor-client-core:$ktor_version") implementation("io.ktor:ktor-client-cio:$ktor_version") }
ktor-client-core is a core dependency that provides the main client functionality, while ktor-client-cio is a dependency for an engine processing network requests.
Click the Load Gradle Changes icon in the top right corner of the build.gradle.kts file to install newly added dependencies.

Create a client

Now we can add a client's code to the src/main/kotlin/Main.kt file:

Replace the existing code in Main.kt with the following:
import io.ktor.client.* import io.ktor.client.engine.cio.* fun main() { val client = HttpClient(CIO) }
A client is represented by the HttpClient class.
To make a request to a specific URL, we need to call a client's method corresponding to an HTTP verb, for example, HttpClient.get. A response will be received as a HttpResponse class object.
import io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.client.request.* import io.ktor.client.statement.* fun main() { val client = HttpClient(CIO) val response: HttpResponse = client.get("https://ktor.io/") }
After adding the code above, the IDE shows the following error for the get function: Suspend function 'get' should be called only from a coroutine or another suspend function.
You can learn more about calling suspending functions from Coroutines basics. In the next step, we'll make our main function suspending to fix this issue.
Click the red bulb and choose Make main suspend.
Finally, add println to print a status code returned by a server. Note that you also need to release resources holding by a client using the close method. The Main.kt file should look in the following way:
import io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.client.request.* import io.ktor.client.statement.* suspend fun main() { val client = HttpClient(CIO) val response: HttpResponse = client.get("https://ktor.io/") println(response.status) client.close() }
In the next section, we'll run our program and make a request.

Run a program and make a request

Now we are ready to run our program to make a request.

Click the gutter icon next to the main function and choose Run 'MainKt'.
Wait until Intellij IDEA runs the application. A server should respond with the 200 OK (hopefully!) message.

Last modified: 19 July 2022