ktor-client-core/io.ktor.client.request/HttpRequestBuilder

HttpRequestBuilder

class HttpRequestBuilder : HttpMessageBuilder

Contains parameters used to make an HTTP request.

Learn more from Making requests.

Constructors

HttpRequestBuilder

constructor()

Types

object Companion

Properties

val attributes: Attributes

Provides access to attributes specific for this request.

The body for this request. Initially EmptyContent.

var bodyType: TypeInfo?

The KType of body for this request. Null for default types that don't need serialization.

executionContext

var executionContext: Job

A deferred used to control the execution of this request.

var HttpRequestBuilder.expectSuccess: Boolean

Terminate HttpClient.receivePipeline if status code is not successful (>=300).

open override val headers: HeadersBuilder

HeadersBuilder to configure the headers for this request.

var HttpRequestBuilder.host: String

Gets the associated URL's host.

var method: HttpMethod

HttpMethod used by this request. HttpMethod.Get by default.

var HttpRequestBuilder.port: Int

Gets the associated URL's port.

val url: URLBuilder

URLBuilder to configure the URL for this request.

Functions

fun HttpMessageBuilder.accept(contentType: ContentType)

Appends the Accept header with a specific contentType.

fun HttpMessageBuilder.basicAuth(username: String, password: String)

Appends the HttpHeaders.Authorization to Basic Authorization with the provided username and password. For advanced configuration use the io.ktor:ktor-client-auth plugin.

fun HttpMessageBuilder.bearerAuth(token: String)

Appends the HttpHeaders.Authorization to Bearer Authorization with the provided token. For advanced configuration use the io.ktor:ktor-client-auth plugin.

fun build(): HttpRequestData

Creates immutable HttpRequestData.

fun HttpMessageBuilder.cookie(name: String, value: String, maxAge: Int = 0, expires: GMTDate? = null, domain: String? = null, path: String? = null, secure: Boolean = false, httpOnly: Boolean = false, extensions: Map<String, String?> = emptyMap())

Appends a single header of key with a specific value if the value is not null.

getCapabilityOrNull

fun <T : Any> getCapabilityOrNull(key: HttpClientEngineCapability<T>): T?

Retrieves capability by the key.

fun HttpMessageBuilder.header(key: String, value: Any?)

Appends a single header of key with a specific value if the value is not null.

fun HttpMessageBuilder.headers(block: HeadersBuilder.() -> Unit): HeadersBuilder

Executes a block that configures the HeadersBuilder associated to this request.

fun HttpRequestBuilder.onDownload(listener: ProgressListener?)

Registers listener to observe download progress.

fun HttpRequestBuilder.onUpload(listener: ProgressListener?)

Registers listener to observe upload progress.

fun HttpRequestBuilder.parameter(key: String, value: Any?)

Appends a single URL query parameter of key with a specific value if the value is not null. Can not be used to set form parameters in the body.

fun HttpRequestBuilder.retry(block: HttpRequestRetryConfig.() -> Unit)

Configures the HttpRequestRetry plugin on a per-request level.

fun setAttributes(block: Attributes.() -> Unit)

Sets request-specific attributes specified by block.

inline fun <T> HttpRequestBuilder.setBody(body: T)

fun HttpRequestBuilder.setBody(body: Any?, bodyType: TypeInfo)

fun <T : Any> setCapability(key: HttpClientEngineCapability<T>, capability: T)

Sets capability configuration.

fun HttpRequestBuilder.skipSavingBody()

Prevent saving response body in memory for the specific request.

fun takeFrom(builder: HttpRequestBuilder): HttpRequestBuilder

Mutates this by copying all the data but execution context from another builder using it as the base.

fun HttpRequestBuilder.takeFrom(request: HttpRequest): HttpRequestBuilder

Mutates this copying all the data from another request using it as base.

fun HttpRequestBuilder.takeFrom(request: HttpRequestData): HttpRequestBuilder

Sets the HttpRequestBuilder from request.

takeFromWithExecutionContext

fun takeFromWithExecutionContext(builder: HttpRequestBuilder): HttpRequestBuilder

Mutates this copying all the data from another builder using it as the base.

fun HttpRequestBuilder.timeout(block: HttpTimeoutConfig.() -> Unit)

Adds timeout boundaries to the request. Requires the HttpTimeout plugin to be installed.

fun url(block: URLBuilder.(URLBuilder) -> Unit)

Executes a block that configures the URLBuilder associated to this request.

fun HttpRequestBuilder.url(url: Url)

Sets the HttpRequestBuilder.url from url.

fun HttpRequestBuilder.url(block: URLBuilder.() -> Unit)

Executes a block that configures the URLBuilder associated to this request.

fun HttpRequestBuilder.url(urlString: String)

Sets the HttpRequestBuilder.url from urlString.

fun HttpRequestBuilder.url(scheme: String? = null, host: String? = null, port: Int? = null, path: String? = null, block: URLBuilder.() -> Unit = {})

Sets the url using the specified scheme, host, port and path. Pass null to keep the existing value in the URLBuilder.