TypedResponseScope

interface TypedResponseScope<out In : Any, out Out : Any, out Failure : FailureSpec, out Params : Parameters>

The various methods available within the handler of a Ktor endpoint.

Full Ktor information is available via call, as is standard in Ktor endpoints.

Properties

body

abstract val body: In

The request body sent by the client.

Spine automatically deserializes this value based on the request type declared in the endpoint.

Example

routing {
    route(Api.Users.logIn) {
        println("User ${body.username} wants to log in…")
        // …
    }
}

call

abstract val call: ApplicationCall

The standard Ktor ApplicationCall instance, which is used to access cookies or any other information directly from Ktor.

Example

routing {
    route(Api.Users.logIn) {
        // …perform log in…

        call.response.cookies.append("my-auth", "123")
        respond(Unit)
    }
}

endpoint

abstract val endpoint: Endpoint<out In, out Out, out Failure, out Params>

The declared Spine endpoint which was called by the user.

parameters

abstract val parameters: Params

The parameters sent by the client.

Spine automatically deserializes this value based on the parameters type declared in the endpoint.

Example

routing {
    route(Api.Users.list) {
        println("Include archived users? ${parameters.includeArchived}")
        // …
    }
}

Functions

fail

@JvmName(name = "fail1")
inline suspend fun <F : Any> TypedResponseScope<*, *, FailureSpec.Or<*, FailureSpec.ByCode<F>>, *>.fail(failure: F): Nothing

@JvmName(name = "fail2")
inline suspend fun <F : Any> TypedResponseScope<, , FailureSpec.Or<FailureSpec.Or<, FailureSpec.ByCode<F>>, Nothing>, >.fail(failure: F): Nothing

@JvmName(name = "fail3")
inline suspend fun <F : Any> TypedResponseScope<, , FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<, FailureSpec.ByCode<F>>, Nothing>, Nothing>, >.fail(failure: F): Nothing

@JvmName(name = "fail4")
inline suspend fun <F : Any> TypedResponseScope<*, *, FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<*, FailureSpec.ByCode<F>>, Nothing>, Nothing>, Nothing>, Nothing>.fail(failure: F): Nothing

@JvmName(name = "fail5")
inline suspend fun <F : Any> TypedResponseScope<*, *, FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<*, FailureSpec.ByCode<F>>, Nothing>, Nothing>, Nothing>, Nothing>, Nothing>.fail(failure: F): Nothing

@JvmName(name = "fail6")
inline suspend fun <F : Any> TypedResponseScope<*, *, FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<FailureSpec.Or<*, FailureSpec.ByCode<F>>, Nothing>, Nothing>, Nothing>, Nothing>, Nothing>, Nothing>.fail(failure: F): Nothing

Fails the endpoint call with one of the declared failures.

Example

routing {
    route(Api.Users.logIn) {
        if (body.password.isBlank()) {
            fail(InvalidPassword)
        }
    }
}

idOf

open fun idOf(resource: DynamicResource<*>): String

Extracts the identifier for a DynamicResource as it was provided by the client.

For example, if we declare the following API:

object Api : RootResource("api") {
    object Users : StaticResource<Api>("users", Api) {
        object User : DynamicResource<Users>("user", Users) {
            val get by get()
        }
    }
}

and the client calls the endpoint GET /api/users/123, then we can declare our route as:

route(Api.Users.User) {
    val id = idOf(Api.Users.User) // "123", because this is what the client passed for this path parameter
}

respond

inline suspend fun <Out : Any> TypedResponseScope<*, Out, *, *>.respond(
    body: Out, 
    code: HttpStatusCode = if (body == Unit) HttpStatusCode.NoContent else HttpStatusCode.OK
)

Responds with the given body.

This method is identical to ApplicationCall.respond but verifies that the body type matches the one declared in the endpoint.

Example

routing {
    route(Api.Users.logIn) {
        val user = authService.verifyLogIn(body.username, body.password)
        respond(user)
    }
}

Parameters

• body: a value of the response type declared in the endpoint. If the endpoint declared a response type of Unit, or declared no response at all, this parameter is optional.

• code: the HTTP status code to respond with. Defaults to HttpStatusCode.NoContent if the response type is Unit or if no response type is declared. Defaults to HttpStatusCode.OK for any other value.

suspend fun TypedResponseScope<*, Unit, *, *>.respond(code: HttpStatusCode = HttpStatusCode.NoContent)

Responds with the given body.

This method is identical to ApplicationCall.respond but verifies that the body type matches the one declared in the endpoint.

Example

routing {
    route(Api.Users.logIn) {
        val user = authService.verifyLogIn(body.username, body.password)
        respond(user)
    }
}

Parameters

• body: a value of the response type declared in the endpoint. If the endpoint declared a response type of Unit, or declared no response at all, this parameter is optional.

• code: the HTTP status code to respond with. Defaults to HttpStatusCode.NoContent if the response type is Unit or if no response type is declared. Defaults to HttpStatusCode.OK for any other value.