Client-side typesafe Spine schema usage • opensavvy.spine.client • request

request¶

inline suspend fun <In : Any, Out : Any, Failure : FailureSpec, Params : Parameters> HttpClient.request(endpoint: ResolvedEndpoint<Endpoint<In, Out, Failure, Params>>, input: In, crossinline parameters: Params.() -> Unit, contentType: ContentType = ContentType.Application.Json, crossinline configure: HttpRequestBuilder.() -> Unit = {}): SpineResponse<Out, Failure>

Invokes a Ktor typesafe endpoint.

If the following API has been declared:

object Api : RootResource("v1") {
    object Users : StaticResource<Api>("users", Api) {
        val list by get()
            .response<List<User>>()

        val create by post()
            .request<UserCreation>()
            .response<User>()

        object User : DynamicResource<Users>("user", Users) {
            val get by get()
                 .response<User>()
        }
    }
}

An HttpClient can be used to call it:

// List users:
client.request(Api / Users / Users.list).bodyOrThrow()

// Create a user:
client.request(Api / Users / Users.create, UserCreation("John", 15)).bodyOrThrow()

// Access a specific user:
client.request(Api / Users / User("123456") / User.get).bodyOrThrow()

For this example to work, you will need to configure the HttpClient's DefaultRequest and ContentNegotiation plugin. To do so, please follow our tutorial.

See also¶

bodyOrNull Access the body, returning null on failure.
bodyOrThrow Access the body, throwing an exception on failure.
handle Exhaustively handle declared failures.

inline suspend fun <Out : Any, Failure : FailureSpec, Params : Parameters> HttpClient.request(endpoint: ResolvedEndpoint<Endpoint<Unit, Out, Failure, Params>>, crossinline parameters: Params.() -> Unit, contentType: ContentType = ContentType.Application.Json, crossinline configure: HttpRequestBuilder.() -> Unit = {}): SpineResponse<Out, Failure>

Invokes a Ktor typesafe endpoint.

If the following API has been declared:

object Api : RootResource("v1") {
    object Users : StaticResource<Api>("users", Api) {
        val list by get()
            .response<List<User>>()

        val create by post()
            .request<UserCreation>()
            .response<User>()

        object User : DynamicResource<Users>("user", Users) {
            val get by get()
                 .response<User>()
        }
    }
}

An HttpClient can be used to call it:

// List users:
client.request(Api / Users / Users.list).bodyOrThrow()

// Create a user:
client.request(Api / Users / Users.create, UserCreation("John", 15)).bodyOrThrow()

// Access a specific user:
client.request(Api / Users / User("123456") / User.get).bodyOrThrow()

For this example to work, you will need to configure the HttpClient's DefaultRequest and ContentNegotiation plugin. To do so, please follow our tutorial.

See also¶

bodyOrNull Access the body, returning null on failure.
bodyOrThrow Access the body, throwing an exception on failure.
handle Exhaustively handle declared failures.

inline suspend fun <In : Any, Out : Any, Failure : FailureSpec> HttpClient.request(endpoint: ResolvedEndpoint<Endpoint<In, Out, Failure, Parameters.Empty>>, input: In, contentType: ContentType = ContentType.Application.Json, crossinline configure: HttpRequestBuilder.() -> Unit = {}): SpineResponse<Out, Failure>

Invokes a Ktor typesafe endpoint.

If the following API has been declared:

object Api : RootResource("v1") {
    object Users : StaticResource<Api>("users", Api) {
        val list by get()
            .response<List<User>>()

        val create by post()
            .request<UserCreation>()
            .response<User>()

        object User : DynamicResource<Users>("user", Users) {
            val get by get()
                 .response<User>()
        }
    }
}

An HttpClient can be used to call it:

// List users:
client.request(Api / Users / Users.list).bodyOrThrow()

// Create a user:
client.request(Api / Users / Users.create, UserCreation("John", 15)).bodyOrThrow()

// Access a specific user:
client.request(Api / Users / User("123456") / User.get).bodyOrThrow()

For this example to work, you will need to configure the HttpClient's DefaultRequest and ContentNegotiation plugin. To do so, please follow our tutorial.

See also¶

bodyOrNull Access the body, returning null on failure.
bodyOrThrow Access the body, throwing an exception on failure.
handle Exhaustively handle declared failures.

inline suspend fun <Out : Any, Failure : FailureSpec> HttpClient.request(endpoint: ResolvedEndpoint<Endpoint<Unit, Out, Failure, Parameters.Empty>>, contentType: ContentType = ContentType.Application.Json, crossinline configure: HttpRequestBuilder.() -> Unit = {}): SpineResponse<Out, Failure>

Invokes a Ktor typesafe endpoint.

If the following API has been declared:

object Api : RootResource("v1") {
    object Users : StaticResource<Api>("users", Api) {
        val list by get()
            .response<List<User>>()

        val create by post()
            .request<UserCreation>()
            .response<User>()

        object User : DynamicResource<Users>("user", Users) {
            val get by get()
                 .response<User>()
        }
    }
}

An HttpClient can be used to call it:

// List users:
client.request(Api / Users / Users.list).bodyOrThrow()

// Create a user:
client.request(Api / Users / Users.create, UserCreation("John", 15)).bodyOrThrow()

// Access a specific user:
client.request(Api / Users / User("123456") / User.get).bodyOrThrow()

For this example to work, you will need to configure the HttpClient's DefaultRequest and ContentNegotiation plugin. To do so, please follow our tutorial.