Skip to main content

Defining request models

Request models define API endpoints and can have the following properties:

  • Path variable in the URL path
  • Query parameter in the URL query string
  • Body parameter

Requirements:

  • Must be annotated with @Serializable and, by default, placed under <api-package>.models (scan packages can be customized via the @GenerateApi annotation)
  • Must have exactly one HTTP method annotation (@GET, @POST, @PUT, @PATCH, @DELETE)
  • Must have a @Returns annotation specifying the response type
  • Class name must end with the Request suffix (e.g., GetUserRequest, CreateOrderRequest)
  • If the class has properties, it must be a data class
  • Classes without properties (marker classes) must be object declarations
  • Cannot be abstract, sealed, or inner

Basic request model example​

import dev.kolibrium.api.ksp.annotations.GET
import dev.kolibrium.api.ksp.annotations.Returns
import kotlinx.serialization.Serializable

@GET("/users")
@Returns(UsersResponse::class)
@Serializable
object ListUsersRequest

Path parameters​

Path variables are defined using curly braces {variableName} and substituted into the URL path.

@GET("/users/{id}/articles/{articleId}")
@Returns(Article::class)
@Serializable
data class GetUserArticleRequest(
    @Path @Transient val id: Int = 0,
    @Path @Transient val articleId: Int = 0
)

Requirements:

  • Must be annotated with both @Path and @Transient
  • Must be one of: String, Int, Long, Short, Float, Double, Boolean
  • Must have a matching path variable in the URL

Query parameters​

Query parameters are appended to the URL as query strings.

@GET("/users")
@Returns(UserList::class)
@Serializable
data class ListUsersRequest(
    @Query @Transient val page: Int? = null,
    @Query @Transient val limit: Int? = null,
    @Query @Transient val search: String? = null
)

Requirements:

  • Must be annotated with both @Query and @Transient
  • Must be nullable (query parameters are optional)
  • Only allowed on GET and DELETE requests
  • Must be one of: String?, Int?, Long?, Boolean?, Short?, Float?, Double?, or List<T>? where T is one of these types

Header parameters​

Header parameters are sent as HTTP headers in the request. Unlike query parameters, headers are allowed on any HTTP method.

@GET("/users")
@Returns(UserList::class)
@Serializable
data class ListUsersRequest(
    @Header(name = "X-Correlation-ID") @Transient val correlationId: String? = null,
    @Header @Transient val accept: String? = null
)

By default, the property name is used as the HTTP header name. Use the name parameter to specify a different header name — this is useful when the HTTP header name contains characters that aren't valid Kotlin identifiers (e.g., X-Correlation-ID).

A null value means the header is not sent.

Requirements:

  • Must be annotated with both @Header and @Transient
  • Must be nullable
  • Must be one of: String?, Int?, Long?, Short?, Float?, Double?, Boolean?
  • Cannot be combined with @Path or @Query
  • Header name must be a valid HTTP header name per RFC 7230

Body parameters​

Body parameters are serialized as the request body (JSON).

@POST("/users")
@Returns(User::class)
@Serializable
data class CreateUserRequest(
    var name: String? = null,
    var email: String? = null,
    var age: Int? = null
)

Requirements:

  • Only allowed on POST, PUT, and PATCH requests
  • Should be var to support the DSL builder pattern
  • Must be nullable or have a default value
  • Not annotated with @Path, @Query, or @Header