Builder

sealed interface Builder

The super-type for the endpoint declaration syntax.

See AnyEndpoint to learn more about the syntax.

This interface uses the same trick as AnyEndpoint to avoid source-incompatible breaking changes. See its documentation for details.

Functions

failure

abstract fun <S : FailureSpec> failure(spec: S): AnyEndpoint.Builder

Declares a possible failure that can happen when calling this endpoint.

When the failure is thrown, the request ends with the HTTP status code described in the failure: FailureSpec.ByCode.statusCode.

Under the hood, this method uses Ktor's content negotiation features. Therefore, all types that would be valid with content negotiation can be used with this library. Note that you may need to perform some configuration on the Ktor side before using some types, see the official documentation for instructions.

Multiple different failures may be declared, though some failures may or may not support that. See FailureSpec to learn more about combining failures.

Example

@Serializable
data class UserAlreadyExists(
    val id: String,
) {

    companion object : FailureCompanion<UserAlreadyExists>(HttpStatusCode.Conflict)
}

val create by post()
    .request<UserCreationDto>()
    .response<UserDto>()
    .failure(UserAlreadyExists)

See also

• FailureSpec: Learn more about failures.

• FailureCompanion: Learn more about binding an error to a type.

abstract fun <F> failure(statusCode: HttpStatusCode): AnyEndpoint.Builder

Declares a possible failure that can happen when calling this endpoint.

When the failure is thrown, the request ends with the provided HTTP statusCode.

Under the hood, this method uses Ktor's content negotiation features. Therefore, all types that would be valid with content negotiation can be used with this library. Note that you may need to perform some configuration on the Ktor side before using some types, see the official documentation for instructions.

Multiple different failures may be declared by calling this function multiple times, but no two calls should have the same <strong>statusCode</strong>. See FailureSpec to learn more about combining failures.

Example

@Serializable
data class UserAlreadyExists(val id: String)

val create by post()
    .request<UserCreationDto>()
    .response<UserDto>()
    .failure<UserAlreadyExists>(HttpStatusCode.Conflict)

See also

• FailureSpec: Learn more about failures.

parameters

abstract fun <P : Parameters> parameters(build: ParameterConstructor<P>): AnyEndpoint.Builder

Declares query parameters that the client will need to provide to the server.

To learn more about representing parameters, see Parameters.

Example

// Create a type to hold the parameters
class UserListParams(data: ParameterStorage) : Parameters(data) {
   var onlyActive: Boolean by parameter(default = false)
   var createdAfter: Instant? by parameter()
}

val list by get()
    .parameters(::UserListParams)
    .response<UserDto>()

request

abstract fun <T : Any> request(type: KType): AnyEndpoint.Builder

Declares the request body type.

When a client makes a request to the server, the client will need to pass an instance of this type.

Under the hood, this method uses Ktor's content negotiation features. Therefore, all types that would be valid with content negotiation can be used with this library. Note that you may need to perform some configuration on the Ktor side before using some types, see the official documentation for instructions.

Do not specify the type parameter. It will be passed automatically when declaring the endpoint.

Example

val list by post()
    .request<UserCreationDto>()
    .response<UserDto>()

If this method is called multiple times, only the last call is retained.

See also

• response

response

abstract fun <T : Any> response(type: KType): AnyEndpoint.Builder

Declares the response body type.

When a client makes a request to the server, the server will respond with an instance of this type.

Under the hood, this method uses Ktor's content negotiation features. Therefore, all types that would be valid with content negotiation can be used with this library. Note that you may need to perform some configuration on the Ktor side before using some types, see the official documentation for instructions.

Do not specify the type parameter. It will be passed automatically when declaring the endpoint.

Example

val list by post()
    .request<UserCreationDto>()
    .response<UserDto>()

If this method is called multiple times, only the last call is retained.

See also

• request