Skip to content

Usage

With the library properly installed, lets start with the basics and learn how to send requests with Klopik.

Send Requests

The easiest way to send requests with Klopik is using one of its static methods.

GET request

You can use the Klopik.get function, passing a URL as parameter, to send an HTTP GET request. Like this:

1
2
3
val response = Klopik.get("https://httpbin.org/get").execute()
println("Status Code: ${response.statusCode}")
println("Response Body: ${response.text}")

In this example, the status code and the response body are printed to the console.

POST, DELETE and other requests

If you wish to make other requests like POST, DELETE, etc., the process is very similar to GET and you just need to call one of the static methods available like Klopik.post, Klopik.delete, etc.

Another way to send any type request is by calling the function Klopik.request instead. The Klopik.request function behaves in the same a Klopik.get, Klopik.post or Klopik.delete would, with the only difference being an extra parameter where you must define what method you want to use.

For example, if I want to send a DELETE request, I can use either option below to achieve the same result:

1
2
3
val url = "https://httpbin.org/delete"
val r1 = Klopik.delete(url).execute()                 // These requests
val r2 = Klopik.request(Method.Delete, url).execute() // do the same thing

RequestOptions

This is great, but most requests require more than just a URL. You may need to send headers, query parameters, a request body, etc. To do this, you can use the RequestOptions class as a second parameter in the request functions.

1
2
3
4
val response = Klopik.post("https://httpbin.org/post") {
    headers = mapOf("Authorization" to "Bearer 0123456789ABCDEF")
    body = """{"name": "Vinicius"}"""
}.execute()

The request above sends a POST request to the URL https://httpbin.org/post with a header Authorization and a JSON body. Both fields are optional and you can use them as needed.

The RequestOptions class has many other options that you can use to customize your requests. Check the API documentation for more information.

Custom client

Using static methods is the easiest way to send requests, but you can also create a custom client if you need more control over the requests and want to make sure that they share the same configuration.

For example, lets say that your application needs to access a REST API where all URLs shared the same base URL. Instead of repeating the base URL in every request, you can create a custom client with the base URL already set:

1
2
3
4
5
6
7
val client = Klopik("https://httpbin.org/")

// This request will be sent to https://httpbin.org/user-agent
val response1 = client.get("user-agent").execute()

// This request will be sent to https://httpbin.org/cache/42
val response2 = client.get("cache/42").execute()

Another use case for custom clients is when you need to access protected endpoints that require authentication. You can set the authentication headers in the client and all requests will be sent with the same headers.

1
2
3
4
5
6
7
val client = Klopik("https://httpbin.org/") {
    headers = mapOf("Authorization" to "Bearer 0123456789ABCDEF")
}

// Both requests will be sent with the Authorization header
val response1 = client.get("anything/protected1").execute()
val response2 = client.get("anything/protected2").execute()

Request Object

You probably noticed in the examples above that when you use one of the request functions, like Klopik.get, Klopik.post and others, they don't execute the request right away. These functions create a Request object; you need one of its methods to actually send the request.

The methods are presented below:

execute() method

This is a synchronous method that sends the request and waits for the response. It returns a complete response object with all the information you need.

stream() method

This is also a synchronous method that sends the request, but instead of returning a complete response object all at once, instead the callback parameter passed to this function is called every time a new chunk of data is received. This is useful when you are dealing with large responses and you don't want to load the entire response into memory at once.

Response Object