REST client
The dev.kilua.rest.RestClient
class, located in the kilua-rest
module, can be used to connect to any HTTP service. You can use remote services with both dynamic and type-safe calls (using @Serializable
classes). The RestClient
class has only a single receive()
method, which uses the builder pattern for configuration and returns a RestResponse<T>
object. A number of extension functions is defined, which allow you to make typical calls easier.
requestDynamic()
RestResponse<JsAny>
request()
RestResponse<T>
(T
- type-safe value)
callDynamic()
JsAny?
call()
T
- type-safe value
Configuration
You can configure HTTP request both when creating a RestClient
instance and also when calling individual methods.
val restClient = RestClient {
headers = {
listOf(
"User-Agent" to "KiluaApp"
)
}
baseUrl = "https://api.github.com"
serializersModule = SerializersModule { // custom serializers for any data types
polymorphic(A::class) {
subclass(B::class)
subclass(C::class)
}
}
}
val searchResult: SearchResult = restClient.call("https://api.github.com/search/repositories", Query("kilua")) {
method = HttpMethod.Post
contentType = "application/json"
headers = {
listOf(
"User-Agent" to "KiluaApp"
)
}
}
Examples
Check the following examples of different http calls.
Dynamic parameters, dynamic result
import dev.kilua.rest.callDynamic
val restClient = RestClient()
val result: JsAny? = restClient.callDynamic("https://api.github.com/search/repositories") {
data = jsObjectOf("q" to "kilua")
}
Dynamic parameters, type-safe result
import dev.kilua.rest.call
@Serializable
data class Repository(val id: Int, val full_name: String?, val description: String?, val fork: Boolean)
val restClient = RestClient()
val items: List<Repository> = restClient.call("https://api.github.com/search/repositories") {
data = jsObjectOf("q" to "kilua")
resultTransform = { it?.jsGet("items") }
}
Type-safe parameters, dynamic result
import dev.kilua.rest.callDynamic
@Serializable
data class Query(val q: String?)
val restClient = RestClient()
val result: JsAny? = restClient.callDynamic("https://api.github.com/search/repositories", Query("kilua"))
Type-safe parameters, type-safe result
import dev.kilua.rest.call
@Serializable
data class Query(val q: String?)
@Serializable
data class SearchResult(val total_count: Int, val incomplete_results: Boolean)
val restClient = RestClient()
val searchResult: SearchResult = restClient.call("https://api.github.com/search/repositories", Query("kilua"))
RestResponse class
A wrapper RestResponse
class is defined as:
public data class RestResponse<T>(val data: T?, val textStatus: String, val response: Response)
When using receive()
,request()
or requestDynamic()
functions, the returned RestResponse
object gives you access to the returned data as well as the native Response
object, which gives you access to the server response (e.g. to get HTTP header values and other information):
import dev.kilua.rest.requestDynamic
val restClient = RestClient()
val restResponse: RestResponse<JsAny> = restClient.requestDynamic("https://api.github.com/search/repositories") {
data = jsObjectOf("q" to "kilua")
}
println(restResponse.response.headers.get("Content-Type")) // application/json; charset=utf-8
Last updated