Ktor is a flexible library that provides the ability to create a non-blocking HTTP client, which enables you to perform requests and handle responses. Its functionality could be enhanced with plugins, such as logging, serialization, authentication, and so on. Its core benefit is that it’s a lightweight framework that can be used on different platforms such as Android, JVM, or Native!

General Overview

Let’s discuss some basic information for everyone to be on the same page.

Today, we are going to write HTTP requests and receive responses. There are different types of requests but OpenWeatherMap for the most part utilizes GET requests with various parameters.

OpenWeatherMap API, as you can tell by its name, is an API for retrieving weather-related data. It provides various types of data but we’re going to use only 3 of them:

• Current Weather,
• 3-hours Forecast,
• and Air Pollution API.

To start using OpenWeatherMap you need to register and get your special API key. It has lots of free options and for our sake, we don’t need to pay at all.

But be aware of the limitations of the call: 1,000 API calls per day for free!

Gradle Dependencies

For this project, we’re going to use basic Ktor’s client, serialization, engines, and logging.

Your build.gradle.kts file would look like this:

val ktor_version: String by project
val kotlin_version: String by project
val logback_version: String by project

plugins {
    kotlin("jvm") version "1.9.21"
    id("io.ktor.plugin") version "2.3.6"
    id("org.jetbrains.kotlin.plugin.serialization") version "1.9.21"
    application
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.ktor:ktor-client-core-jvm")
    implementation("io.ktor:ktor-client-cio-jvm")

    implementation("io.ktor:ktor-serialization-kotlinx-json-jvm")
    implementation("io.ktor:ktor-client-content-negotiation-jvm")

    implementation("ch.qos.logback:logback-classic:$logback_version")
    implementation("io.ktor:ktor-client-logging:$ktor_version")
    implementation("io.ktor:ktor-client-apache5:$ktor_version")

    testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")
}

Creating Models

The first step of creating a Ktor client is actually revealing what we’re gonna handle. Basically, we need 2 types of models: request and response. All necessary information is located on the corresponding page of the documentation. The documentation is pretty neat and, generally, it’s a good practice to check it out during the coding!

To optimize the process we could spot similar parameters appearing in the Current Weather and Weather Forecast. Such as Mode and Units.

So we can create separate classes and use the latter like this:

enum class ResponseUnits {
    STANDARD,
    METRIC,
    IMPERIAL
}

enum class ResponseMode {
    XML
}

Now let’s create the request themselves.

As there are some optional parameters present we’re going to make them nullable with default value null so that we could use them or not with ease.

Here are the models for requests:

data class CurrentWeatherRequest(
    val latitude: Double,
    val longitude: Double,
    val mode: ResponseMode? = null,
    val units: ResponseUnits? = null,
    val language: String? = null
)

data class WeatherForecastRequest(
    val latitude: Double,
    val longitude: Double,
    val mode: ResponseMode? = null,
    val units: ResponseUnits? = null,
    val language: String? = null,
    val count: Int? = null
)

data class AirPollutionRequest(
    val latitude: Double,
    val longitude: Double
)

Consequently, we desperately need models to put our data to: the response models.

It’s the most routine process because there are some huge responses and by ‘huge’ I mean lots of parameters. Let’s dive deep into one model and the rest would be easy to create.

Here’s what our JSON of current weather data looks like (there is also a text representation of this JSON with more information about parameters):

{
  "coord": {
    "lon": 10.99,
    "lat": 44.34
  },
  "weather": [
    {
      "id": 501,
      "main": "Rain",
      "description": "moderate rain",
      "icon": "10d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 298.48,
    "feels_like": 298.74,
    "temp_min": 297.56,
    "temp_max": 300.05,
    "pressure": 1015,
    "humidity": 64,
    "sea_level": 1015,
    "grnd_level": 933
  },
  "visibility": 10000,
  "wind": {
    "speed": 0.62,
    "deg": 349,
    "gust": 1.18
  },
  "rain": {
    "1h": 3.16
  },
  "clouds": {
    "all": 100
  },
  "dt": 1661870592,
  "sys": {
    "type": 2,
    "id": 2075663,
    "country": "IT",
    "sunrise": 1661834187,
    "sunset": 1661882248
  },
  "timezone": 7200,
  "id": 3163858,
  "name": "Zocca",
  "cod": 200
}

Now we have to face some difficulties. Not only do we have to parse it but also there are some optional parameters.

To solve the first issue we mark our classes with @Serializable and @SerialName annotations. I highly recommend using @SerialName because it provides enhanced readability and usability especially when handling such long classes.

To solve the second problem I recommend you to read my detailed guide that covers all essential information about Serialization. Basically, if we want to parse all of the data, we make optional fields with @EncodeDefault and make it nullable with the default value as null. This makes sure that if there was no such a field we would get a null, without any exceptions.

Now let’s look at classes for our Ktor client:

@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class CurrentWeather(
    @SerialName("coord") val coordinates: Coordinates,
    @SerialName("weather") val weather: List<Weather>,
    @SerialName("base") val base: String,
    @SerialName("main") val main: Main,
    @SerialName("visibility") val visibility: Int,
    @SerialName("wind") val wind: Wind,
    @SerialName("rain")
    @EncodeDefault
    val rain: Rain? = null,
    @SerialName("snow")
    @EncodeDefault
    val snow: Snow? = null,
    @SerialName("clouds") val clouds: Clouds,
    @SerialName("dt") val dateTime: Long,
    @SerialName("sys") val systemData: SystemData,
    @SerialName("timezone") val timezone: Int,
    @SerialName("id") val cityId: Int,
    @SerialName("name") val cityName: String,
    @SerialName("cod") val code: Int
) {

    //other classes here

    @Serializable
    data class Wind(
        @SerialName("speed") val speed: Double,
        @SerialName("deg") val direction: Int,
        @SerialName("gust") val gust: Double
    )

    @Serializable
    data class Rain(
        @SerialName("1h")
        @EncodeDefault
        val oneHour: Double? = null,
        @SerialName("3h")
        @EncodeDefault
        val threeHours: Double? = null
    )

	//other classes here
}

The rest of the responses are quite similar so you could check them out in the repository that comes with this article.

Quick remark, I’ve made classes such as Coordinates, Weather, etc. as inner classes since there are the same classes for other responses but with different structures.

This approach helps not to mix them up.

Creating The Ktor Client Itself

We are gonna be using Ktor’s HttpClient with some adjustments and extended configuration.

Let’s check it out:

private val client = HttpClient(Apache5) {
        install(ContentNegotiation) {
            json(Json {
                isLenient = false
            })
        }
        install(Logging)
        defaultRequest {
            url {
                protocol = URLProtocol.HTTPS
                host = "api.openweathermap.org/data/2.5"
            }
        }
    }

First of all, we have the Apache5 engine rather than CIO, for example, because it’s suitable for HTTP/2 while CIO is not.

Next, we have 2 plugins: the ContentNegotiation for the JSON parsing and the Logging for detailed logs.

Also, as all of our requests to OpenWeatherMap have similar endpoints, we can use defaultRequest to shorten our request’s links. The whole defaultRequest translates to https://api.openweathermap.org/data/2.5/. We’ll combine this with the request’s specific parameters.

Now let’s talk about them.

Creating Routes

As all of our routes would share similar logic let’s look closely at only one of them for the Current Weather:

suspend fun getCurrentWeather(currentWeatherRequest: CurrentWeatherRequest): CurrentWeather? {
        return try {
            val response: HttpResponse = client
                .get("/weather") {
                    url {
                        parameters.append("lat", currentWeatherRequest.latitude.toString())
                        parameters.append("lon", currentWeatherRequest.longitude.toString())
                        parameters.append("appid", APP_ID)
                        if (currentWeatherRequest.mode != null) parameters.append(
                            "mode",
                            currentWeatherRequest.mode.name()
                        )
                        if (currentWeatherRequest.units != null) parameters.append(
                            "units",
                            currentWeatherRequest.units.name()
                        )
                        if (currentWeatherRequest.language != null) parameters.append(
                            "lang",
                            currentWeatherRequest.language
                        )
                    }
                }

            if (response.status == HttpStatusCode.OK) {
                response.body<CurrentWeather>()
            } else {
                println("Failed to retrieve current weather. Status: ${response.status}")
                null
            }
        } catch (e: Exception) {
            println("Error retrieving current weather: ${e.message}")
            null
        }
    }

Here we create GET HttpResponse with the path “/weather” and then we specify additional parameters, note that it’ll automatically use the correct notation(? and other).

In the URL block, we list all of our parameters using parameters.append() function that takes the name and the value. There is no need to include optional parameters that are not specified, so we simply check whether they’re null or not.

Our Ktor client also implements error handling.

For the errors with the request itself, such as connection problems, any issues from the server, etc. we’ll get the “Error retrieving current weather:” message and null result.

And if your request is successful but has some undesired response, in our case everything except 200 OK, we’ll get “Failed to retrieve current weather. Status:” and null result as well.

Ktor Client In Action

To use the client you could simply call our object with the corresponding method like this:

WeatherClient.getCurrentWeather(
        CurrentWeatherRequest(
            latitude = 44.34,
            longitude = 10.99,
            units = ResponseUnits.IMPERIAL,
            language = "pl"
        )
    )
	
	WeatherClient.getWeatherForecast(
        WeatherForecastRequest(
            latitude = 44.34,
            longitude = 10.99,
            units = ResponseUnits.IMPERIAL,
            language = "pl"
        )
    )
	
	WeatherClient.getAirPollution(
        AirPollutionRequest(
            latitude = 50.0,
            longitude = 50.0
        )
    )

This could be used on every platform but as I’ve mentioned before make sure you’re using the correct engine!

Summary

And that’s all for this article about the OpenWeatherMap API Ktor client.

If you would like to download the full source code, then you can find it in this GitHub repository.

Lastly, thank you for being here, and happy to hear your feedback in the comments section below!

The post How To Create a Ktor Client To Connect To OpenWeatherMap API appeared first on Codersee blog- Kotlin on the backend.

• Ktor Server
• Ktor Client
• WebSockets in Ktor

Before we start, I just wanted to note that we are going to use a modified project from the lesson about Ktor with Ktorm and PostgreSQL. So if you don’t know how to set up and use a Ktor server with PostgreSQL you should definitely check it up, because I will skip the basics. Additionally, if you’d like to explore kotlinx.serialization in details, then check out my detailed guide.

Lastly, please note that there is a GitHub repository for all of this in the end of this lesson!

Setup

A few quick words about setting up. Note that for the main thing we are going to use, such as ContentNegotiation, Ktor has different implementations for Client and Server.

Do not mess them up, it causes a lot of trouble and a lot of Stack Overflow questions 🙂

//server
implementation("io.ktor:ktor-server-content-negotiation-jvm")
//client
implementation("io.ktor:ktor-client-content-negotiation-jvm")

kotlinx.serialization With Ktor Server

Now, let’s start with the kotlinx.serialization for the Ktor server part.

I am going to use Postman for making HTTP requests and testing the server. You can use any tool for this purpose even the client we will write about in the next part 🙂

First of all, let’s check our classes for the User from previous parts:

interface User : Entity<User> {  
  companion object : Entity.Factory<User>()  
  
  val userId: Long?  
  var userName: String  
}

 Now we are going to need classes for our responses: 

@Serializable  
data class UserResponse(  
  val userId: Long,  
  val userName: String  
)  
  
@Serializable  
data class UserRequest(  
  val userName: String  
)

@Serializable  
data class UserErrorResponse(val message: String)

Basically, the central part of all serialization here is ContentNegotiation which could be installed for our server(not the client).

As we are using it for Json serialization, we should specify it as json() like this:

fun Application.configureSerialization() {  
  install(ContentNegotiation) {  
    json(Json {  
      prettyPrint = true  
      isLenient = true  
    })  
  }  
}

And here’s our loved Json object! Now we can do all kinds of trickery that we know and learned before.

For the code above, I’ve used a simple style specification, but you can use it as you like. As an example, we can add a custom or polymorphic serializer:

private val contextualSerializerModule = SerializersModule {
  contextual<Date>(DateAsStringSerializer)
}

private val polymorphicSerializationModule = SerializersModule {
  polymorphic(User::class) {
    subclass(Admin::class, Admin.serializer())
    subclass(Guest::class, Guest.serializer())
  }
}

object DateAsStringSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor(
    "Date", 
    PrimitiveKind.STRING,
  )

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

And our server is going to look like this: 

fun Application.configureSerialization() {
  install(ContentNegotiation) {
    json(Json {
      prettyPrint = true
      isLenient = true
      serializersModule = contextualSerializerModule
      serializersModule = polymorphicSerializationModule
    })
  }
}

We can remove this for now, we’ll use actual polymorphic serialization in the Web Sockets section.

Now, what about routes? Let’s check out a simple POST request:

fun Route.createUser(userService: UserService) {
  post {

    val request = call.receive<UserRequest>()

    val success = userService.createUser(userRequest = request)

    if (success)
      call.respond(HttpStatusCode.Created)
    else
      call.respond(HttpStatusCode.BadRequest, UserErrorResponse("Cannot create user"))
  }
}

As we can see, we don’t serialize/deserialize anything manually.

The whole process happens due to this line:

val request = call.receive<UserRequest>()

We can witness that our request deserializes into the UserRequest as such is marked with @Serializable annotation.

The same happens here:

fun Route.updateUserByIdRoute(userService: UserService) {
  patch("/{userId}") {
    val userId: Long = call.parameters["userId"]?.toLongOrNull()
      ?: return@patch call.respond(
          HttpStatusCode.BadRequest, 
          UserErrorResponse("Invalid id")
        )

    val request = call.receive<UserRequest>()
    val success = userService.updateUserById(userId, request)

    if (success)
      call.respond(HttpStatusCode.NoContent)
    else
      call.respond(
        HttpStatusCode.BadRequest,
        UserErrorResponse("Cannot update user with id [$userId]"),
      )
  }
}

Our request is deserialized and we can update a user.

Now let’s test it and get our users:

private fun User?.toUserResponse(): UserResponse? =  
    this?.let { UserResponse(it.userId!!, it.userName) }

fun Route.getAllUsersRoute(userService: UserService) {  
    get {  
        val users = userService.findAllUsers()  
            .map(User::toUserResponse)  
  
        call.respond(message = users)  
    }  
}

As I said before, I’m going to use Postman.

So how about checking our server:

Post:

Delete:

kotlinx.serialization With Ktor Client

Now the kotlinx.serialization for the Ktor client. Here’s the same thing, but make sure you don’t miss anything and use ContentNegotiation FOR CLIENT.

Check the import:

import io.ktor.client.plugins.contentnegotiation.*

We can install it just like before:

private val client = HttpClient(CIO) {
  install(ContentNegotiation) {
    json(Json {
      prettyPrint = true
      isLenient = true
    })
  }
  defaultRequest {
    url {
      host = "0.0.0.0"
      path("/")
      port = 8080
    }
  }}

All things apply here as well, so let’s check how to use it for our requests. There are lots of possible situations, we are going to cover basic data retrieving and how to place something inside a body of a request.

We want to get all of the users, what should we do? We can use something like this:

suspend fun getAllUsers(): List<UserResponse> {
  return try {
    val response: HttpResponse = client.get("/users")

    if (response.status == HttpStatusCode.OK) {
      response.body<List<UserResponse>>()
    } else {
      println("Failed to retrieve users. Status: ${response.status}")
      emptyList()
    }
  } catch (e: Exception) {
    println("Error retrieving users: ${e.message}")
    emptyList()
  }
}

The main part here as well is this:

response.body<List<UserResponse>>()

The UserResponse class can be serialized, and we don’t need to do anything at all. All hail the ContentNegotiation 🙂

How about we create some user? We can do it as well:

suspend fun createUser(user: UserRequest) {
  try {
    val response: HttpResponse = client.post("/users") {
      contentType(ContentType.Application.Json)
      setBody(user)
    }

    if (response.status == HttpStatusCode.Created) {
      println("User created successfully")
    } else {
      println("Failed to create user. Status: ${response.status}")
    }
  } catch (e: Exception) {
    println("Error creating user: ${e.message}")
  }
}

This time, we specify the content type for our body, such as ContentType.Application.Json and just set our user in here. All happens as it is a miracle.

Now let’s test it. I’m going to use this simply to check each method:

runBlocking {

  val allUsersOld = UserRequests.getAllUsers()
  println("All Users: $allUsersOld")

  val newUser = UserRequest(
    userName = "Mark"
  )

  UserRequests.createUser(newUser)

  val allUsersNew = UserRequests.getAllUsers()
  println("All Users: $allUsersNew")

  val userIdToRetrieve = 2L
  val retrievedUser = UserRequests.getUserById(userIdToRetrieve)
  println("User with ID $userIdToRetrieve: $retrievedUser")

  val userIdToUpdate = 2L
  val updatedUser = UserRequest(
    userName = "Bob"
  )
  UserRequests.updateUserById(userIdToUpdate, updatedUser)

  val userIdToDelete = 2L
  UserRequests.deleteUserById(userIdToDelete)
}

And the corresponding result would be something like this:

...
All Users: [UserResponse(userId=2, userName=User #2)]
...
User created successfully
...
All Users: [UserResponse(userId=2, userName=User #2), UserResponse(userId=7, userName=Mark)]
...
User with ID 2: UserResponse(userId=2, userName=User #2)
...
User updated successfully
...
User deleted successfully

I’ve skipped the logs because they are not important for this. 

Web Sockets

So, here’s the fun part. There is no Content Negotiation for the Web Sockets 🙁

Nonetheless, there is such thing as contentConverter for WebSockets:

private val client = HttpClient(CIO).config {
  install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(
      Json
    )
  }
}

Basically, that’s it, now we can use sendSerialized() and receiveDeserialized() to send and receive data.

However, let’s focus more on manual implementation for the sake of understanding. Here we have classes to represent our messages:

@Serializable
abstract class Message {
  abstract val content: String
}

@Serializable
@SerialName("text")
class TextMessage(override val content: String) : Message()

@Serializable
@SerialName("system")
class SystemMessage(override val content: String, val systemInfo: String) : Message()

private val module = SerializersModule {
  polymorphic(Message::class) {
    subclass(TextMessage::class, TextMessage.serializer())
    subclass(SystemMessage::class, SystemMessage.serializer())
  }
}

val messagesFormat = Json {
  serializersModule = module
}

We are going to use TextMessage to send to the server and SystemMessage to send back from the server.

To send a message we must serialize it to string. And to receive vice versa. Nothing difficult: 

@OptIn(ExperimentalSerializationApi::class)
private suspend fun DefaultClientWebSocketSession.receiveMessage() {
  try {
    for (message in incoming) {
      message as? Frame.Text ?: continue
      val deserializedMessage: Message =
        messagesFormat.decodeFromStream(message.data.inputStream())
      println("${deserializedMessage.content} // ${(deserializedMessage as? SystemMessage)?.systemInfo}")
    }
  } catch (e: Exception) {
    println("Error while receiving: " + e.localizedMessage)
  }
}

private suspend fun DefaultClientWebSocketSession.sendMessage(message: Message) {
  val serializedMessage = messagesFormat.encodeToString(message)
  try {
    send(serializedMessage)
  } catch (e: Exception) {
    println("Some error occur: " + e.localizedMessage)
    return
  }
}

Here’s our simple server that going to get our message and send it back with some changes:

routing {
  webSocket("/hello") {
    try {
      for (frame in incoming) {
        frame as? Frame.Text ?: continue
        val deserializedMessage: WebSocketSession.Message =
          WebSocketSession.messagesFormat.decodeFromStream(frame.data.inputStream())
        val newMessageText = deserializedMessage.content + " - from Client"
        val serializedMessage = WebSocketSession.messagesFormat.encodeToString<WebSocketSession.Message>(
          WebSocketSession.SystemMessage(
            content = newMessageText,
            systemInfo = "Important"
          )
        )
        Connection(this).session.send(serializedMessage)
      }
    } catch (e: Exception) {
      println(e.localizedMessage)
    }
  }
}

The final part is to test it. We simply connect it to our already existing server:

fun main() {
  embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
    configureUserRoutes()
    configureSerialization()
    configureSockets()
  }.start(wait = true)
}

And now run the client, for example, I’ve created this one:

suspend fun connectWebSocket() {
  client.webSocket(
    host = "0.0.0.0",
    port = 8080,
    path = "/hello"
  ) {
    launch { sendMessage(TextMessage("Good morning!")) }
    launch { receiveMessage() }
    delay(2000)
    launch { sendMessage(TextMessage("Hello!")) }
    launch { receiveMessage() }
    delay(2000)
    println("Connection closed. Goodbye!")
    client.close()
  }
}

runBlocking {
  WebSocketSession.connectWebSocket()
}

Here’s the results:

2023-12-01 15:46:26.104 [DefaultDispatcher-worker-4] TRACE io.ktor.websocket.WebSocket - Sending Frame TEXT (fin=true, buffer len = 41) from session io.ktor.websocket.DefaultWebSocketSessionImpl@2e8ab815
2023-12-01 15:46:26.110 [DefaultDispatcher-worker-6] TRACE io.ktor.websocket.WebSocket - WebSocketSession(StandaloneCoroutine{Active}@4ecfdc65) receiving frame Frame TEXT (fin=true, buffer len = 82)
Good morning! - from Client // Important
2023-12-01 15:46:28.094 [DefaultDispatcher-worker-6] TRACE io.ktor.websocket.WebSocket - Sending Frame TEXT (fin=true, buffer len = 34) from session io.ktor.websocket.DefaultWebSocketSessionImpl@2e8ab815
2023-12-01 15:46:28.097 [DefaultDispatcher-worker-3] TRACE io.ktor.websocket.WebSocket - WebSocketSession(StandaloneCoroutine{Active}@4ecfdc65) receiving frame Frame TEXT (fin=true, buffer len = 75)
Hello! - from Client // Important
Connection closed. Goodbye!

Summary

And that’s all for this article about kotlinx.serialization with Ktor.

If you would like to download the full source code, then you can find it in this GitHub repository.

Lastly, thank you for being here, and happy to hear your feedback in the comments section below!

The post How To Use kotlinx.serialization with Ktor and Kotlin? appeared first on Codersee blog- Kotlin on the backend.