Making requests
After setting up the client, you can make HTTP requests. The main way of making HTTP requests is the request function that can take a URL as a parameter. Inside this function, you can configure various request parameters:
Specify an HTTP method, such as
GET
,POST
,PUT
,DELETE
,HEAD
,OPTION
, orPATCH
.Specify a URL as a string or configure URL components (a domain, a path, query parameters, etc.) separately.
Add headers and cookies.
Set the body of a request, for example, a plain text, a data object, or form parameters.
These parameters are exposed by the HttpRequestBuilder class.
Note that this function allows you to receive a response as an HttpResponse
object. HttpResponse
exposes the API required to get a response body in various ways (a string, a JSON object, etc.) and obtain response parameters, such as a status code, content type, headers, and so on. You can learn more from the Receiving responses topic.
Specify an HTTP method
When calling the request
function, you can specify the desired HTTP method using the method
property:
In addition to the request
function, HttpClient
provides specific functions for basic HTTP methods: get, post, put, and so on. For example, you can replace the above request with the following code:
In both examples, a request URL is specified as a string. You can also configure URL components separately using HttpRequestBuilder.
Specify a request URL
The Ktor client allows you to configure a request URL in the following ways:
Pass the entire URL string
val response: HttpResponse = client.get("https://ktor.io/docs/welcome.html")Configure URL components separately
client.get { url { protocol = URLProtocol.HTTPS host = "ktor.io" path("docs/welcome.html") } }In this case, the
url
parameter exposed byHttpRequestBuilder
is used. This parameter accepts URLBuilder and provides more flexibility in building URLs.
Path segments
In the previous example, we've specified the entire URL path using the URLBuilder.path
property. You can also pass individual path segments using the appendPathSegments
function.
Note that appendPathSegments
encodes path segments. To disable encoding, use appendEncodedPathSegments
.
Query parameters
To add query string parameters, use the URLBuilder.parameters
property:
Note that parameters
encodes query parameters. To disable encoding, use encodedParameters
.
URL fragment
A hash mark #
introduces the optional fragment near the end of the URL. You can configure a URL fragment using the fragment
property.
Note that fragment
encodes a URL fragment. To disable encoding, use encodedFragment
.
Set request parameters
In this section, we'll see how to specify various request parameters, including an HTTP method, headers, and cookies. If you need to configure some default parameters for all requests of a specific client, use the DefaultRequest plugin.
Headers
To add headers to the request, you can use the following ways:
The headers function allows you to add several headers at once:
client.get("https://ktor.io") { headers { append(HttpHeaders.Accept, "text/html") append(HttpHeaders.Authorization, "abc123") append(HttpHeaders.UserAgent, "ktor client") } }The header function allows you to append a single header.
The
basicAuth
andbearerAuth
functions add theAuthorization
header with a corresponding HTTP scheme.
Cookies
To send cookies, use the cookie function:
Ktor also provides the HttpCookies plugin that allows you to keep cookies between calls. If this plugin is installed, cookies added using the cookie
function are ignored.
Set request body
To set the body of a request, you need to call the setBody
function exposed by HttpRequestBuilder. This function accepts different types of payloads, including plain text, arbitrary class instances, form data, byte arrays, and so on. Below, we'll take a look at several examples.
Text
Sending plain text as body can be implemented in the following way:
Objects
With the enabled ContentNegotiation plugin, you can send a class instance within a request body as JSON. To do this, pass a class instance to the setBody
function and set the content type to application/json
using the contentType function:
You can learn more from the Content negotiation and serialization help section.
Form parameters
The Ktor client provides the submitForm function for sending form parameters using both x-www-form-urlencoded
and multipart/form-data
types. The example below shows how to send form parameters encoded as multipart/form-data
:
url
specifies a URL for making a request.formParameters
a set of form parameters built usingparameters
.
You can find the full example here: client-submit-form.
Upload a file
If you need to send a file with a form, you can use the following approaches:
Use the submitFormWithBinaryData function. In this case, a boundary will be generated automatically.
Call the
post
function and pass the MultiPartFormDataContent instance to thesetBody
function. Note that theMultiPartFormDataContent
constructor also allows you to pass a boundary value.
For both approaches, you need to build form data using the formData function.
MultiPartFormDataContent
also allows you to override a boundary and content type as follows:
You can find the full examples here:
Binary data
To send binary data with the application/octet-stream
content type, pass the ByteReadChannel instance to the setBody
function. For example, you can use the File.readChannel function to open a read channel for a file and fill it:
You can find the full example here: client-upload-binary-data.
Parallel requests
When sending two requests at once, the client suspends the second request execution until the first one is finished. If you need to perform several requests at once, you can use launch or async functions. The code snippet below shows how to perform two requests asynchronously:
To see a full example, go to client-parallel-requests.
Cancel a request
If you need to cancel a request, you can cancel a coroutine that runs this request. The launch function returns a Job
that can be used to cancel the running coroutine:
Learn more from Cancellation and timeouts.