library/xyz.malefic.koven.contract/ApiContract

ApiContract

abstract class ApiContract<Req, Res, ReqH, ResH, PathP, QueryP, CookieP>(val path: String, val httpMethod: HttpMethod = HttpMethod.POST, val requestHeaderDecoder: HeaderField<ReqH> = Empty as HeaderField<ReqH>, val responseHeaderDecoder: HeaderField<ResH> = Empty as HeaderField<ResH>, val pathDecoder: PathField<PathP> = Empty as PathField<PathP>, val queryDecoder: QueryField<QueryP> = Empty as QueryField<QueryP>, val cookieDecoder: CookieField<CookieP> = Empty as CookieField<CookieP>, val requestFormat: BodyFormat<Req>, val responseFormat: BodyFormat<Res>, val isProtected: Boolean = false)

A contract for an API endpoint shared between the client and server.

Parameters

path

The path of the API endpoint. Automatically prefixed with "api/".

httpMethod

The HTTP method to use for the API endpoint. Defaults to HttpMethod.POST.

requestHeaderDecoder

The HeaderField to decode the request headers.

responseHeaderDecoder

The HeaderField to decode the response headers.

pathDecoder

The PathField to decode the path parameters.

queryDecoder

The QueryField to decode the query parameters.

cookieDecoder

The CookieField to decode the request cookies.

requestFormat

The BodyFormat to use for the request body. Defaults to UnitFormat or JsonFormat.

responseFormat

The BodyFormat to use for the response body. Defaults to UnitFormat or JsonFormat.

isProtected

Whether the API endpoint requires authentication. Defaults to false.

Type Parameters

Req

The type of the request body. If the request body is empty, this should be Unit.

Res

The type of the response body. If the response body is empty, this should be Unit.

ReqH

The type of the request headers. Use Empty for no headers.

ResH

The type of the response headers. Use Empty for no headers.

PathP

The type of the path parameters. Use Empty for no path parameters.

QueryP

The type of the query parameters. Use Empty for no query parameters.

CookieP

The type of the request cookies. Use Empty for no cookies.

Constructors

ApiContract

constructor(path: String, httpMethod: HttpMethod = HttpMethod.POST, requestHeaderDecoder: HeaderField<ReqH> = Empty as HeaderField<ReqH>, responseHeaderDecoder: HeaderField<ResH> = Empty as HeaderField<ResH>, pathDecoder: PathField<PathP> = Empty as PathField<PathP>, queryDecoder: QueryField<QueryP> = Empty as QueryField<QueryP>, cookieDecoder: CookieField<CookieP> = Empty as CookieField<CookieP>, requestFormat: BodyFormat<Req>, responseFormat: BodyFormat<Res>, isProtected: Boolean = false)

Properties

cookieDecoder

val cookieDecoder: CookieField<CookieP>

httpMethod

val httpMethod: HttpMethod

isProtected

val isProtected: Boolean

path

val path: String

pathDecoder

val pathDecoder: PathField<PathP>

queryDecoder

val queryDecoder: QueryField<QueryP>

requestFormat

val requestFormat: BodyFormat<Req>

requestHeaderDecoder

val requestHeaderDecoder: HeaderField<ReqH>

responseFormat

val responseFormat: BodyFormat<Res>

responseHeaderDecoder

val responseHeaderDecoder: HeaderField<ResH>

Functions

call

inline suspend fun <Req, Res, ReqH, ResH, PathP, QueryP, CookieP> ApiContract<Req, Res, ReqH, ResH, PathP, QueryP, CookieP>.call(request: Req = Unit as Req, headers: ReqH = Empty as ReqH, pathParams: PathP = Empty as PathP, queryParams: QueryP = Empty as QueryP, cookies: CookieP = Empty as CookieP, crossinline headerBlock: Headers.Builder.() -> Unit = {}): Either<Issue, ApiResponse<Res, ResH>>

Extension to make calling contracts more ergonomic.

decodeCookies

context(_: Raise<Issue>)
open fun decodeCookies(cookies: Map<String, String>): CookieP

Decodes the request cookies into the type CookieP.

decodePath

context(_: Raise<Issue>)
open fun decodePath(params: Map<String, String>): PathP

Decodes the path parameters into the type PathP.

decodeQuery

context(_: Raise<Issue>)
open fun decodeQuery(params: QueryParams): QueryP

Decodes the query parameters into the type QueryP.

decodeRequestHeaders

context(_: Raise<Issue>)
open fun decodeRequestHeaders(headers: Headers): ReqH

Decodes the request headers into the type ReqH. Can be overridden to provide custom header decoding.

decodeResponseHeaders

context(_: Raise<Issue>)
open fun decodeResponseHeaders(headers: Headers): ResH

Decodes the response headers into the type ResH. Can be overridden to provide custom header decoding.

inline fun <Req, Res, ReqH, ResH, PathP, QueryP, CookieP> ApiContract<Req, Res, ReqH, ResH, PathP, QueryP, CookieP>.register(filter: Filter = Filter.NoOp, crossinline handler: context(Request, Raise<Issue>, ReqH, CookieP, Principal) ApiContract<Req, Res, ReqH, ResH, PathP, QueryP, CookieP>.(Req, PathP, QueryP) -> ApiResponse<Res, ResH>): RoutingHttpHandler

Creates a route for the given ApiContract.

@JvmName(name = "registerSimple")

inline fun <Req, Res, ReqH, ResH, CookieP> ApiContract<Req, Res, ReqH, ResH, Empty, Empty, CookieP>.register(filter: Filter = Filter.NoOp, crossinline handler: context(Request, Raise<Issue>, ReqH, CookieP, Principal) ApiContract<Req, Res, ReqH, ResH, Empty, Empty, CookieP>.(Req) -> ApiResponse<Res, ResH>): RoutingHttpHandler

Simplifies registration for ApiContract types with no path or query parameters.

@JvmName(name = "registerUnit")

inline fun <Req, ReqH, PathP, QueryP, CookieP> ApiContract<Req, Unit, ReqH, Empty, PathP, QueryP, CookieP>.register(filter: Filter = Filter.NoOp, crossinline handler: context(Request, Raise<Issue>, ReqH, CookieP, Principal) ApiContract<Req, Unit, ReqH, Empty, PathP, QueryP, CookieP>.(Req, PathP, QueryP) -> Unit): RoutingHttpHandler

Overload for register that allows returning Unit when the response body is Unit and headers are Empty.

@JvmName(name = "registerSimpleUnit")

inline fun <Req, ReqH, CookieP> ApiContract<Req, Unit, ReqH, Empty, Empty, Empty, CookieP>.register(filter: Filter = Filter.NoOp, crossinline handler: context(Request, Raise<Issue>, ReqH, CookieP, Principal) ApiContract<Req, Unit, ReqH, Empty, Empty, Empty, CookieP>.(Req) -> Unit): RoutingHttpHandler

Overload for register (simple) that allows returning Unit when the response body is Unit and headers are Empty.

registerMultipart

inline fun <Res, ReqH, ResH, PathP, QueryP, CookieP> ApiContract<Multipart, Res, ReqH, ResH, PathP, QueryP, CookieP>.registerMultipart(filter: Filter = Filter.NoOp, crossinline handler: context(Request, Raise<Issue>, ReqH, CookieP, Principal) ApiContract<Multipart, Res, ReqH, ResH, PathP, QueryP, CookieP>.(Multipart, PathP, QueryP) -> ApiResponse<Res, ResH>): RoutingHttpHandler

Creates a route for the given ApiContract with a multipart request body.

registerPaginated

inline fun <Req, T, ReqH, ResH, PathP, QueryP, CookieP> ApiContract<Req, PaginatedResponse<T>, ReqH, ResH, PathP, QueryP, CookieP>.registerPaginated(filter: Filter = Filter.NoOp, crossinline handler: context(Request, Raise<Issue>, ReqH, CookieP, Principal) ApiContract<Req, PaginatedResponse<T>, ReqH, ResH, PathP, QueryP, CookieP>.(Req, PathP, QueryP, Pagination) -> ApiResponse<List<T>, ResH>): RoutingHttpHandler

Creates a route for the given ApiContract that returns a paginated response with a Pagination context.

response

fun <Req, Res, ReqH, ResH, PathP, QueryP, CookieP> ApiContract<Req, Res, ReqH, ResH, PathP, QueryP, CookieP>.response(status: Int = 200, block: ApiResponse.Companion.Builder<Res, ResH>.() -> Unit): ApiResponse<Res, ResH>

Creates an ApiResponse for this contract with a DSL-type Builder.