ktor-client-core/io.ktor.client/HttpClient

HttpClient

class HttpClient(val engine: HttpClientEngine, userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig()) : CoroutineScope, Closeable

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.

You can learn how to create a configure HttpClient from Creating and configuring a client.

Constructors

HttpClient

constructor(engine: HttpClientEngine, userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig())

Properties

attributes

val attributes: Attributes

Typed attributes used as a lightweight container for this client.

coroutineContext

open override val coroutineContext: CoroutineContext

engine

val engine: HttpClientEngine

HttpClientEngine used to execute network requests.

engineConfig

val engineConfig: HttpClientEngineConfig

Provides access to the client's engine configuration.

monitor

val monitor: Events

Provides access to the events of the client's lifecycle.

receivePipeline

val receivePipeline: HttpReceivePipeline

A pipeline used for receiving a request.

requestPipeline

val requestPipeline: HttpRequestPipeline

A pipeline used for processing all requests sent by this client.

responsePipeline

val responsePipeline: HttpResponsePipeline

A pipeline used for processing all responses sent by the server.

sendPipeline

val sendPipeline: HttpSendPipeline

A pipeline used for sending a request.

Functions

open override fun close()

Closes the underlying engine.

config

fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient

Returns a new HttpClient by copying this client's configuration and additionally configured by the block parameter.

suspend fun HttpClient.cookies(url: Url): List<Cookie>

Gets all the cookies for the specified url for this HttpClient.

suspend fun HttpClient.cookies(urlString: String): List<Cookie>

Gets all the cookies for the specified urlString for this HttpClient.

defaultTransformers

fun HttpClient.defaultTransformers()

Install default transformers. Usually installed by default so there is no need to use it unless you have disabled it via HttpClientConfig.useDefaultTransformers.

delete

inline suspend fun HttpClient.delete(builder: HttpRequestBuilder): HttpResponse

Executes a HttpClient DELETE request with the parameters configured in builder.

inline suspend fun HttpClient.delete(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's DELETE request with the parameters configured in block.

inline suspend fun HttpClient.delete(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient HEAD request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.delete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's DELETE request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

get

inline suspend fun HttpClient.get(builder: HttpRequestBuilder): HttpResponse

Executes an HttpClient's GET request with the parameters configured in builder.

inline suspend fun HttpClient.get(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's GET request with the parameters configured in block.

inline suspend fun HttpClient.get(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient GET request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.get(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's GET request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

head

inline suspend fun HttpClient.head(builder: HttpRequestBuilder): HttpResponse

Executes a HttpClient HEAD request with the parameters configured in builder.

inline suspend fun HttpClient.head(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's HEAD request with the parameters configured in block.

inline suspend fun HttpClient.head(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient HEAD request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.head(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's HEAD request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

isSupported

fun isSupported(capability: HttpClientEngineCapability<*>): Boolean

Checks if the specified capability is supported by this client.

mapEngineExceptions

fun CoroutineScope.mapEngineExceptions(input: ByteReadChannel, request: HttpRequestData): ByteReadChannel

Returns ByteReadChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException.

fun CoroutineScope.mapEngineExceptions(output: ByteWriteChannel, request: HttpRequestData): ByteWriteChannel

Returns ByteWriteChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException.

options

inline suspend fun HttpClient.options(builder: HttpRequestBuilder): HttpResponse

Executes a HttpClient OPTIONS request with the parameters configured in builder.

inline suspend fun HttpClient.options(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's OPTIONS request with the parameters configured in block.

inline suspend fun HttpClient.options(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient OPTIONS request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.options(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's OPTIONS request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

patch

inline suspend fun HttpClient.patch(builder: HttpRequestBuilder): HttpResponse

Executes a HttpClient PATCH request with the parameters configured in builder.

inline suspend fun HttpClient.patch(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's PATCH request with the parameters configured in block.

inline suspend fun HttpClient.patch(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient PATCH request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.patch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's PATCH request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

plugin

fun <B : Any, F : Any> HttpClient.plugin(plugin: HttpClientPlugin<B, F>): F

Returns a plugin installed in HttpClient.

pluginOrNull

fun <B : Any, F : Any> HttpClient.pluginOrNull(plugin: HttpClientPlugin<B, F>): F?

Returns a plugin installed in this client. Returns null if the plugin was not previously installed.

post

inline suspend fun HttpClient.post(builder: HttpRequestBuilder): HttpResponse

Executes an HttpClient's POST request with the parameters configured in builder.

inline suspend fun HttpClient.post(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's POST request with the parameters configured in block.

inline suspend fun HttpClient.post(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient POST request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.post(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's POST request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

prepareDelete

inline suspend fun HttpClient.prepareDelete(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's DELETE request with the parameters configured in builder.

inline suspend fun HttpClient.prepareDelete(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's DELETE request with the parameters configured in block.

inline suspend fun HttpClient.prepareDelete(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient HEAD request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.prepareDelete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's DELETE request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

prepareForm

inline suspend fun HttpClient.prepareForm(formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

suspend fun HttpClient.prepareForm(url: String, formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a request containing form parameters encoded using the x-www-form-urlencoded format.

prepareFormWithBinaryData

inline suspend fun HttpClient.prepareFormWithBinaryData(formData: List<PartData>, crossinline block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

inline suspend fun HttpClient.prepareFormWithBinaryData(url: String, formData: List<PartData>, crossinline block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a POST request containing form parameters encoded using the multipart/form-data format.

prepareGet

inline suspend fun HttpClient.prepareGet(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's GET request with the parameters configured in builder.

inline suspend fun HttpClient.prepareGet(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's GET request with the parameters configured in block.

inline suspend fun HttpClient.prepareGet(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient GET request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.prepareGet(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's GET request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

prepareHead

inline suspend fun HttpClient.prepareHead(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's HEAD request with the parameters configured in builder.

inline suspend fun HttpClient.prepareHead(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's HEAD request with the parameters configured in block.

inline suspend fun HttpClient.prepareHead(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient HEAD request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.prepareHead(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's HEAD request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

prepareOptions

inline suspend fun HttpClient.prepareOptions(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's OPTIONS request with the parameters configured in builder.

inline suspend fun HttpClient.prepareOptions(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's OPTIONS request with the parameters configured in block.

inline suspend fun HttpClient.prepareOptions(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient OPTIONS request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.prepareOptions(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's OPTIONS request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

preparePatch

inline suspend fun HttpClient.preparePatch(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's PATCH request with the parameters configured in builder.

inline suspend fun HttpClient.preparePatch(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's PATCH request with the parameters configured in block.

inline suspend fun HttpClient.preparePatch(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient PATCH request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.preparePatch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's PATCH request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

preparePost

inline suspend fun HttpClient.preparePost(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's POST request with the parameters configured in builder.

inline suspend fun HttpClient.preparePost(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's POST request with the parameters configured in block.

inline suspend fun HttpClient.preparePost(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient POST request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.preparePost(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's POST request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

preparePut

inline suspend fun HttpClient.preparePut(builder: HttpRequestBuilder): HttpStatement

Prepares an HttpClient's PUT request with the parameters configured in builder.

inline suspend fun HttpClient.preparePut(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's PUT request with the parameters configured in block.

inline suspend fun HttpClient.preparePut(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares a HttpClient PUT request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.preparePut(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's PUT request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

prepareRequest

inline suspend fun HttpClient.prepareRequest(builder: HttpRequestBuilder = HttpRequestBuilder()): HttpStatement

Prepares an HttpClient's request with the parameters specified using builder.

inline suspend fun HttpClient.prepareRequest(block: HttpRequestBuilder.() -> Unit): HttpStatement

Prepares an HttpClient's request with the parameters specified using block.

inline suspend fun HttpClient.prepareRequest(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's request with the url and the parameters configured in block.

inline suspend fun HttpClient.prepareRequest(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement

Prepares an HttpClient's request with the urlString and the parameters configured in block.

put

inline suspend fun HttpClient.put(builder: HttpRequestBuilder): HttpResponse

Executes a HttpClient PUT request with the parameters configured in builder.

inline suspend fun HttpClient.put(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's PUT request with the parameters configured in block.

inline suspend fun HttpClient.put(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes a HttpClient PUT request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

inline suspend fun HttpClient.put(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's PUT request with the specified url and an optional block receiving an HttpRequestBuilder for configuring the request.

request

inline suspend fun HttpClient.request(builder: HttpRequestBuilder = HttpRequestBuilder()): HttpResponse

Executes an HttpClient's request with the parameters specified using builder.

inline suspend fun HttpClient.request(block: HttpRequestBuilder.() -> Unit): HttpResponse

Executes an HttpClient's request with the parameters specified in block.

inline suspend fun HttpClient.request(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's request with the url and the parameters configured in block.

inline suspend fun HttpClient.request(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Executes an HttpClient's request with the urlString and the parameters configured in block.

serverSentEvents

suspend fun HttpClient.serverSentEvents(request: HttpRequestBuilder.() -> Unit, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: suspend ClientSSESession.() -> Unit)

suspend fun HttpClient.serverSentEvents(urlString: String, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, request: HttpRequestBuilder.() -> Unit = {}, block: suspend ClientSSESession.() -> Unit)

suspend fun HttpClient.serverSentEvents(scheme: String? = null, host: String? = null, port: Int? = null, path: String? = null, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, request: HttpRequestBuilder.() -> Unit = {}, block: suspend ClientSSESession.() -> Unit)

Opens a block with ClientSSESession.

serverSentEventsSession

suspend fun HttpClient.serverSentEventsSession(reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: HttpRequestBuilder.() -> Unit): ClientSSESession

suspend fun HttpClient.serverSentEventsSession(urlString: String, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: HttpRequestBuilder.() -> Unit = {}): ClientSSESession

suspend fun HttpClient.serverSentEventsSession(scheme: String? = null, host: String? = null, port: Int? = null, path: String? = null, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: HttpRequestBuilder.() -> Unit = {}): ClientSSESession

Opens a ClientSSESession.

sse

suspend fun HttpClient.sse(request: HttpRequestBuilder.() -> Unit, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: suspend ClientSSESession.() -> Unit)

suspend fun HttpClient.sse(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: suspend ClientSSESession.() -> Unit)

suspend fun HttpClient.sse(scheme: String? = null, host: String? = null, port: Int? = null, path: String? = null, request: HttpRequestBuilder.() -> Unit = {}, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: suspend ClientSSESession.() -> Unit)

Opens a block with ClientSSESession.

sseSession

suspend fun HttpClient.sseSession(reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: HttpRequestBuilder.() -> Unit): ClientSSESession

suspend fun HttpClient.sseSession(urlString: String, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: HttpRequestBuilder.() -> Unit = {}): ClientSSESession

suspend fun HttpClient.sseSession(scheme: String? = null, host: String? = null, port: Int? = null, path: String? = null, reconnectionTime: Duration? = null, showCommentEvents: Boolean? = null, showRetryEvents: Boolean? = null, block: HttpRequestBuilder.() -> Unit = {}): ClientSSESession

Opens a ClientSSESession.

submitForm

inline suspend fun HttpClient.submitForm(formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

suspend fun HttpClient.submitForm(url: String, formParameters: Parameters = Parameters.Empty, encodeInQuery: Boolean = false, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Makes a request containing form parameters encoded using the x-www-form-urlencoded format.

submitFormWithBinaryData

inline suspend fun HttpClient.submitFormWithBinaryData(formData: List<PartData>, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

inline suspend fun HttpClient.submitFormWithBinaryData(url: String, formData: List<PartData>, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse

Makes a POST request containing form parameters encoded using the multipart/form-data format.

toString

open override fun toString(): String

webSocket

suspend fun HttpClient.webSocket(request: HttpRequestBuilder.() -> Unit, block: suspend DefaultClientWebSocketSession.() -> Unit)

suspend fun HttpClient.webSocket(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit)

suspend fun HttpClient.webSocket(method: HttpMethod = HttpMethod.Get, host: String? = null, port: Int? = null, path: String? = null, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit)

Opens a block with DefaultClientWebSocketSession.

webSocketSession

suspend fun HttpClient.webSocketSession(block: HttpRequestBuilder.() -> Unit): DefaultClientWebSocketSession

suspend fun HttpClient.webSocketSession(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): DefaultClientWebSocketSession

suspend fun HttpClient.webSocketSession(method: HttpMethod = HttpMethod.Get, host: String? = null, port: Int? = null, path: String? = null, block: HttpRequestBuilder.() -> Unit = {}): DefaultClientWebSocketSession

Opens a DefaultClientWebSocketSession.

suspend fun HttpClient.ws(request: HttpRequestBuilder.() -> Unit, block: suspend DefaultClientWebSocketSession.() -> Unit)

suspend fun HttpClient.ws(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit)

suspend fun HttpClient.ws(method: HttpMethod = HttpMethod.Get, host: String? = null, port: Int? = null, path: String? = null, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit)

Opens a block with DefaultClientWebSocketSession.

wss

suspend fun HttpClient.wss(request: HttpRequestBuilder.() -> Unit, block: suspend DefaultClientWebSocketSession.() -> Unit)

suspend fun HttpClient.wss(urlString: String, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit)

suspend fun HttpClient.wss(method: HttpMethod = HttpMethod.Get, host: String? = null, port: Int? = null, path: String? = null, request: HttpRequestBuilder.() -> Unit = {}, block: suspend DefaultClientWebSocketSession.() -> Unit)

Opens a block with secure DefaultClientWebSocketSession.