Hello! In this article, I would like to show you how to use Retrofit 2 with Kotlin coroutines.

Please keep in mind, that this blog post is a continuation of the previous ultimate retrofit guide and we will focus on how to adjust the project to work properly with Kotlin coroutines. If you haven’t seen it yet, then you should definitely do that before heading to this one.

Either way, I can assure you that after finishing these two tutorials, you will have a full understanding of Retrofit and its features.

I’ve created this article as a response to Uduak comment- thank you for your feedback and I’m always happy to chat with you all 🙂

Finally, please keep in mind that the official support for coroutines has been added in Retrofit2 version 2.6.0.

2. Retrofit Kotlin Coroutines Imports

As the first step, we have to add coroutines functionality to our existing project.

To do so, we will use the kotlinx-coroutines-core. And to be on the same page, I will be using the version: 1.6.4.
 

2.1. Maven

If you are working with Maven, then you can add it to your project with the following lines:

<dependency>
  <groupId>org.jetbrains.kotlinx</groupId>
  <artifactId>kotlinx-coroutines-core</artifactId>
  <version>(VERSION)</version>
</dependency>

2.2. Gradle

Alternatively, we can use Gradle to fetch the library:

// build.gradle
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:<VERSION>'
// build.gradle.kts
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:<VERSION>")

3. Edit UserApi

Nextly, let’s navigate to the UserApi interface and make the necessary changes.

Please keep in mind, that the changes I’m gonna cover here can be applied to each function inside the UserApi (but to avoid boilerplate, I’ll focus on the GET function):

Note: as always, you can find the link to GitHub repository with all examples in the end of this article 🙂

interface UserApi {
  @GET("users")
  suspend fun getUsers(): Response<List<User>>
}

As we can see, only two adjustments are necessary here:

• add suspend modifier- which in the coroutine’s context means that our function can be suspended (paused) and resumed (without blocking),
• replace a Call with a Response – per the release notes, underneath it behaves just like fun getUsers(): Response<List<User>> invoked with Call.enqueue.

Of course, if we are not interested in headers and status codes, then we can simply return the List of users:

interface UserApi {
  @GET("users")
  suspend fun getUsers(): List<User>
}

4. Retrofit Client and Interceptors

When it comes to the Retrofit client with Kotlin coroutines- we can keep it as it is:

object RetrofitClient {

  // Base URL must end in /
  private const val BASE_URL = "http://localhost:8090/v1/"

  private val okHttpClient = OkHttpClient()
    .newBuilder()
    .addInterceptor(AuthorizationInterceptor)
    .addInterceptor(RequestInterceptor)
    .build()

  fun getClient(): Retrofit =
    Retrofit.Builder()
      .client(okHttpClient)
      .baseUrl(BASE_URL)
      .addConverterFactory(JacksonConverterFactory.create())
      .build()
}

object RequestInterceptor : Interceptor {
  override fun intercept(chain: Interceptor.Chain): Response {
    val request = chain.request()
    println("Outgoing request to ${request.url()}")
    return chain.proceed(request)
  }
}

object AuthorizationInterceptor : Interceptor {
  override fun intercept(chain: Interceptor.Chain): Response {
    val requestWithHeader = chain.request()
      .newBuilder()
      .header(
        "Authorization", UUID.randomUUID().toString()
      ).build()
    return chain.proceed(requestWithHeader)
  }
}

5. Retrofit User Service

On the other hand, we need to make small adjustments to the UserService class:

class UserService {

  private val retrofit = RetrofitClient.getClient()
  private val userApi = retrofit.create(UserApi::class.java)

  suspend fun successfulUsersResponse() {
    val usersResponse = userApi.getUsers()

    val successful = usersResponse.isSuccessful
    val httpStatusCode = usersResponse.code()
    val httpStatusMessage = usersResponse.message()

    val body: List<User>? = usersResponse.body()

  }

  suspend fun errorUsersResponse() {
    val usersResponse = userApi.getUsers()

    val errorBody: ResponseBody? = usersResponse.errorBody()

    val mapper = ObjectMapper()
    val mappedBody: ErrorResponse? = errorBody?.let { notNullErrorBody ->
      mapper.readValue(notNullErrorBody.string(), ErrorResponse::class.java)
    }
  }

  suspend fun headersUsersResponse() {
    val usersResponse = userApi.getUsers()

    val headers = usersResponse.headers()
    val customHeaderValue = headers["custom-header"]
  }
}

As we can see, we don’t have to invoke the execute() method anymore. In addition, we must mark functions with suspend– because the getUsers() can be either called only from a coroutine or another suspend function.

Finally, if we want to read the error body, we have to make use of the string() method, instead of toString(). As the name suggests, this one returns the response as a String. When we run the toString(), we will eventually end up with a runtime exception.

6. Test Retrofit With Kotlin Coroutines

As the last step, let’s test our Retrofit 2 functionality with Kotlin coroutines.

Although most probably, you will incorporate it into your Android project, to keep this blog post universal, I’ve prepared a simple main() function:

fun main() = runBlocking {
  val service = UserService()

  coroutineScope {
    launch(Dispatchers.IO) {
      delay(10_000)

      println("[${Thread.currentThread().name}] One")

      service.successfulUsersResponse()
    }
    launch(Dispatchers.IO) {
      println("[${Thread.currentThread().name}] Two")

      service.successfulUsersResponse()
    }
  }

  println("[${Thread.currentThread().name}] Done!")
}

If we run our program, we should see the following:

[DefaultDispatcher-worker-3] Two

# 10 seconds of delay

[DefaultDispatcher-worker-3] One

[main] Done!

As we can clearly see, everything is working as expected.

7. Retrofit With Kotlin Coroutines Summary

And that would be all for this blog post about Retrofit 2 with Kotlin coroutines.

As always, the source code for this article can be found in this GitHub repository.

Finally, if you enjoyed this content, or would like to ask me about anything, please let me know in the comments section below 🙂

The post Retrofit With Kotlin Coroutines: What You Need To Know appeared first on Codersee blog- Kotlin on the backend.

In this article, I would like to show you the Jackson @JsonView annotation and how to use it, when working Spring Boot and Kotlin.

@JsonView is an annotation used to instruct the Jackson mapper, whether the annotated field is a part of the view and should be serialized, or not. And I know, it might sound a bit complicated, but in the next few minutes, I will prove that it is only a first impression.

2. Prepare Spring Boot Project

2.1. Setup

But before we dive into the @JsonView, let’s configure our sandbox Spring Boot project first. As always, I highly encourage you to use the Spring Initializr page to do it. Just to be on the same page, I am using the following settings:

• Language: Kotlin
• Spring Boot version: 2.7.2
• Java: 17
• Dependencies: Spring Web
• Jackson version: 2.13.3

Moreover, you can find the link to the repository with all examples in the Summary section for this article.

2.2. Prepare DTO

With that being done, let’s create a data class called ArticleDto:

data class ArticleDto(
  val id: Long,
  val title: String,
  val category: String,
  val content: String,
  val views: Long,
  val likes: Long
)

As we can see, this class is responsible for transferring the data about an article on a blog.

2.2. Implement Controller Class

Following, let’s introduce the ArticleController to our codebase:

@RestController
@RequestMapping("/articles")
class ArticleController {

  private val articles = mapOf(
    1L to ArticleDto(
      1L, "Article 1", "Spring Framework",
      "Content 1", 1000, 30
    ),
    2L to ArticleDto(
      2L, "Article 2", "Kotlin",
      "Content 2", 5000, 54
    )
  )

  @GetMapping
  fun getAllArticles(): List<ArticleDto> =
    articles.values.toList()

  @GetMapping("/{id}")
  fun getArticleDetails(@PathVariable id: Long): ArticleDto? =
    articles[id]

  @GetMapping("/{id}/analytics")
  fun getArticleAnalytics(@PathVariable id: Long): ArticleDto? =
    articles[id]
}

As can be seen, in our example, we exposed 3 different endpoints:

• /articles – used to populate the list of articles
• /articles/{id} – to obtain the details of an article by its identifier
• /articles/{id}/analytics – to obtain the analytics data

2.3. Check Endpoints

With that being done, let’s quickly check how our Spring Boot app behaves without @JsonView.

Let’s query the /articles endpoint:

#Result: 

[
  {
    "id": 1,
    "title": "Article 1",
    "category": "Spring Framework",
    "content": "Content 1",
    "views": 1000,
    "likes": 30
  },
  {
    "id": 2,
    "title": "Article 2",
    "category": "Kotlin",
    "content": "Content 2",
    "views": 5000,
    "likes": 54
  }
]

Everything is working fine and as a result, we receive a list of our test data.

On the other hand, when we query either the /articles/{id}, or the /articles/{id}/analytics, we see the following:

#Result: 

{
  "id": 1,
  "title": "Article 1",
  "category": "Spring Framework",
  "content": "Content 1",
  "views": 1000,
  "likes": 30
}

At this point, both endpoints work in the same manner, but we will see how to change it in the next chapters.
 

3. How Does the @JsonView Help Me In Spring Boot Then?

So, as I mentioned earlier- these 3 endpoints were created to return the data about all articles, details of the article, and analytics.

As we can clearly see, although they are working, we don’t need all of the data every time and we should limit the response payload:

• /articles – in the case of the list, the information about identifier, title, and category should be sufficient
• /articles/{id} – when querying the details, we would like to get all the information
• /articles/{id}/analytics – we would like to use this one to obtain the views and likes information only

Knowing these requirements we could introduce 3 different DTOs and implement appropriate mappers. Although this solution will work, managing multiple DTOs and mappers may become troublesome at some point. Additionally, in case of any change, we will have to mimic it across each one.

Nevertheless, the @JsonView is a great answer to this problem and in the next chapters, I will show you how to introduce it to our Spring Boot app.

4. Simple @JsonView

With all of that being said, we can finally start working with the @JsonView.

As the first step, let’s create a new Views class with two inner interfaces:

class Views {
  interface List
  interface Analytics
}

Nextly, let’s modify our DTO a bit:

data class ArticleDto(
  @field:JsonView(Views.List::class)
  val id: Long,
  @field:JsonView(Views.List::class)
  val title: String,
  @field:JsonView(Views.List::class)
  val category: String,
  val content: String,
  @field:JsonView(Views.Analytics::class)
  val views: Long,
  @field:JsonView(Views.Analytics::class)
  val likes: Long
)

As we can see, the id, title, and category fields are a part of the List view. On the other hand, the views and likes properties belong to Analytics. If we test our endpoints now, we might be surprised that nothing changed, but that’s the desired state.

To make use of the @JsonView in Spring Boot, we have to annotate our endpoints, as well:

@GetMapping
@JsonView(Views.List::class)
fun getAllArticles(): List<ArticleDto> =
  articles.values.toList()

@JsonView(Views.Analytics::class)
@GetMapping("/{id}/analytics")
fun getArticleAnalytics(@PathVariable id: Long): ArticleDto? =
  articles[id]

With that being done, let’s test these two endpoints once again:

# List view result: 

[
  {
    "id": 1,
    "title": "Article 1",
    "category": "Spring Framework"
  },
  {
    "id": 2,
    "title": "Article 2",
    "category": "Kotlin"
  }
]

# Analytics view result: 

{
  "views": 1000,
  "likes": 30
}

And this time, response payloads are limited to the desired fields only. We don’t have to test the details endpoint, because we already know that nothing changes unless we mark the endpoint with @JsonView annotation.

5. Default View Inclusion

As the next step, let’s take a second to understand the default view inclusion concept.

To do so, let’s add a Config class to our project:

@Configuration
class Config {

  @Bean
  fun objectMapper(): ObjectMapper =
    JsonMapper.builder()
      .enable(MapperFeature.DEFAULT_VIEW_INCLUSION) //don't needed here, enabled by default
      .build()

}

If we specify our bean explicitly, the DEFAULT_VIEW_INCLUSION feature will be enabled by default.

This means, that fields not annotated with @JsonView, will be still serialized. To better visualize it, let’s re-test our endpoints:

# List view result: 

[
  {
    "id": 1,
    "title": "Article 1",
    "category": "Spring Framework",
    "content": "Content 1"
  },
  {
    "id": 2,
    "title": "Article 2",
    "category": "Kotlin",
    "content": "Content 2"
  }
]

# Analytics view result: 

{
  "content": "Content 1",
  "views": 1000,
  "likes": 30
}

As we can see, in both cases non-annotated content field is returned. Sometimes this behavior might be useful, but in some cases, it might cause us trouble, so we have to be aware of this behavior.

6. Extending Views

As the last thing, let’s see another great feature- extending views.

Let’s imagine that we would like to introduce a new endpoint, which will return fields of both List and Analytics views. Let’s call it ListAndAnalytics:

class Views {
  interface List
  interface Analytics
  interface ListAndAnalytics
}

As the next step, we could add our new view everywhere, where List or Analytics is presented:

data class ArticleDto(
  @field:JsonView(Views.List::class, Views.ListAndAnalytics::class)
  val id: Long,
  @field:JsonView(Views.List::class, Views.ListAndAnalytics::class)
  val title: String,
  @field:JsonView(Views.List::class, Views.ListAndAnalytics::class)
  val category: String,
  val content: String,
  @field:JsonView(Views.Analytics::class, Views.ListAndAnalytics::class)
  val views: Long,
  @field:JsonView(Views.Analytics::class, Views.ListAndAnalytics::class)
  val likes: Long
)

And although this works, the code becomes much less readable. (and imagine what will happen if we decide to add even more views)

We can simply avoid that by making our new interface extending the two others:

class Views {
  interface List
  interface Analytics
  interface ListAndAnalytics : List, Analytics
}

And annotate our endpoint appropriately:

@JsonView(Views.ListAndAnalytics::class)
@GetMapping("/{id}/list-and-analytics")
fun getArticleListAndAnalytics(@PathVariable id: Long): ArticleDto? =
  articles[id]

Which, when queried, will produce the following result:

# List and analytics view result: 

{
  "id": 1,
  "title": "Article 1",
  "category": "Spring Framework",
  "views": 1000,
  "likes": 30
}

As we can see, with this simple approach we can easily create a hierarchy of views in our codebase.

5. @JsonView with Spring Boot Summary

And that would be all for this article on what the @JsonView annotation brings to the table when working with Spring Boot. I hope that after reading this tutorial you will be able to apply it to your code and save your precious time during the development

Pssst… if you would like to contribute to Codersee and support the creation of content, you can “buy me a coffee“. Have a great day! 🙂

Also, you can find the source code with examples in this GitHub repository (and other articles related to Jackson on my blog right here).

The post @JsonView With Spring Boot and Kotlin appeared first on Codersee blog- Kotlin on the backend.

Hello friend, in this article I would like to show you a @JsonProperty vs @JsonAlias Jackson annotations comparison.

Together, we will see what exactly these two annotations are and how to use them properly in our, not only Spring Boot projects. As always, we will use the Kotlin programming language, but the things you’re gonna learn today can be easily incorporated into Java projects, as well.

3. Serialization vs Deserialization

Nevertheless, before we dive into the @JsonProperty vs @JsonAlias topic, let’s take a second to distinguish these two terms:

• serialization– is a process of converting an object existing in memory into a stream of bytes, so that it can be stored, or transmitted. In our case, converting Kotlin/Java objects into JSON is an example of serialization
• deserialization– this is the reverse process, in which a stream of bytes (ex. JSON) is converted to an object existing in memory

[elementor-template id=”9007393″]

2. @JsonProperty

2.1. Definition And Defaults

With that being said, let’s answer the question- what exactly the @JsonProperty annotation is?

In Jackson, it is a marker annotation, which can be used to mark non-static methods and fields as a logical property. Simply put, we use it to tell Jackson’s ObjectMapper to map a given JSON field to a particular object field.

By default, the field name is used as a property name:

data class ExampleDto(
    @JsonProperty val id: Long,
    @JsonProperty val name: String
)

As we can see, our example DTO consists of two fields, which when populated with some random data, will be translated to the given JSON:

{
  "id": 1,
  "name": "Piotr"
}

Of course, the above structure will be the same for both serialization and deserialization.

Moreover, if we would leave the above data class without any annotation, the result would be exactly the same.

2.2. So What Do I Need @JsonProperty For?

Although you might think this annotation is useless after the previous sentence, let me walk you through a few use cases.

Definitely, the most popular one is changing the way, we would like the JSON to look. When we specify a non-empty value, then this value will be used:

data class ExampleDto(
    @JsonProperty val id: Long,
    @JsonProperty("person_name") val personName: String
)

And this time, the JSON structure will look, as follows:

{
  "id": 1,
  "person_name": "Piotr"
}

This way, a camel case used in our code is translated to the snake case, often used in REST APIs.

2.3. Different Structure For Serialization And Deserialization

As the next step, let’s see how we can keep JSONs used for serialization and deserialization completely different. Although my example will be a bit extreme, you may encounter a similar situation when working with some external APIs in your project.

Let’s imagine, that you would like to fetch some data from an external API and then forward them to the user querying your endpoint. To do so, you could either use two, separate data classes and perform mapping or simply make use of @JsonProperty possibilities:

data class ExampleDto(
  @JsonProperty("external_id")
  @get:JsonProperty("id_for_user")
  val id: Long,
  
  @JsonProperty("external_name")
  @get:JsonProperty("name_for_user")
  val name: String
)

As can be seen, we made use of the @get, which in Kotlin means that we want to apply the annotation to property getter.

After these modifications, we would be able to read JSON in the following form:

{
  "external_id": 1,
  "external_name": "Piotr"
}

And forward it to the user in this form:

{
  "id_for_user": 1,
  "name_for_user": "Piotr"
}

2.4. @JsonProperty With Enums

Another interesting feature of @JsonProperty is the possibility to use it with enums. However, it’s been added in Jackson 2.6, so you might want to check a version in your project.

Anyway, let’s see the example:

enum class SomeType {
  STANDARD, PREMIUM
}

data class ExampleDto(
  val id: Long,
  val name: String,
  val type: SomeType
)

With the above code, our objects will look, as follows:

{
  "id": 1,
  "name": "Piotr",
  "type": "PREMIUM"
}

However, if we would like to change the JSON form, then we can mark it, as well:

enum class SomeType {
  @JsonProperty("Tier 1")
  STANDARD,
  @JsonProperty("Tier 2")
  PREMIUM
}

After this change, the provided value will be used:

{
  "id": 1,
  "name": "Piotr",
  "type": "Tier 2"
}

This strategy can be useful when we don’t necessarily want to show the implementation details to users.

2.4. Different Access Types

The last thing, I would like to cover before we will see the @JsonProperty vs @JsonAlias comparison are access types.

@JsonProperty lets us set an optional access property to change the way Jackson interprets visibility rules for a given field. Let’s have a look at each one of the 4 access types:

• AUTO (default) – which means that visibility rules will be applied to determine a read/write access of the property.

As always, let’s have a look at the example:

data class ExampleDto(
  @JsonProperty val id: Long,
  @JsonProperty val name: String,
  @JsonProperty private val email: String
)

As we can see, the email property is private, which means, that an example object will be serialized into this form:

{
  "id": 1,
  "name": "Piotr"
}

On the other hand, when we try to deserialize a JSON containing an email property, then it will be read successfully.

• READ_WRITE – this means that property will be accessible for both serialization and deserialization regardless of the visibility rules.

Let’s apply a small change to our DTO:

data class ExampleDto(
  @JsonProperty val id: Long,
  @JsonProperty val name: String,
  @JsonProperty(access = JsonProperty.Access.READ_WRITE) private val email: String
)

This time, the email can be both serialized and deserialized, even though it is private:

{
  "id": 1,
  "name": "Piotr",
  "email": "contact@codersee.com"
}

• READ_ONLY – when applied, a property can be read for serialization, but cannot be set during the deserialization.

With that being said, let’s see another example:

data class ExampleDto(
  @JsonProperty(access = JsonProperty.Access.READ_ONLY) val id: Long?,
  @JsonProperty val name: String
)

As can be seen, the id property has to be set as a nullable type, so that it won’t fail during the deserialization. The serialized object looks as follows:

{
  "id": 1,
  "name": "Piotr"
}

However, when we try to deserialize a JSON with the same payload, the id will be set to null. This access type can be used when we would like to autogenerate id on the backend side and ignore user input.

• WRITE_ONLY – with this one, the property can be set during the deserialization, but cannot be set during the serialization.

And again, let’s see it in action:

data class ExampleDto(
  @JsonProperty(access = JsonProperty.Access.WRITE_ONLY) val id: Long,
  @JsonProperty val name: String
)

This time, the serialized object will have the following form:

{
  "name": "Piotr"
}

Additionally, we still have the possibility to pass an id property, which will be correctly read to an object.

3. @JsonAlias

With all of the above being said, let’s finally see what exactly @JsonAlias is? Since Jackson 2.9, this annotation lets us specify one, or more alternative names accepted during the deserialization.

So, for a given example:

data class ExampleDto(
  val id: Long,
  @JsonAlias("n", "N", "surname")
  val name: String
)

The name value can be set from either n, N, name, or surname property.

If you are wondering now, which value will be chosen, when we specify more than one matching fields, just like here:

{
  "id": 1,
  "surname": "Piotr",
  "N": "John"
}

Then, the answer is- the last one.

Moreover, it can be used with enums, as well.

4. @JsonProperty vs @JsonAlias

Finally, let’s get back to the title of this post, the @JsonProperty vs @JsonAlias comparison.

Well, the most important thing to remember is that the @JsonAlias affects the deserialization process only. Nevertheless, it lets us specify multiple values. This makes it a great choice, when we want to reuse our DTO, or keep backward compatibility (for example, after the refactoring).

In my opinion, this annotation is a great addition to the @JsonProperty but should be used wisely. We don’t want any unwanted value to be set for our property 🙂

5. Summary

And that would be all for this article on @JsonProperty vs @JsonAlias. If you’d like to learn a bit more or check out other annotations, then please refer to the Jackson documentation.

Let me know what are your favorite Jackson annotations. As always, you can do it in the comment section below, or by the contact form.

Finally, if you would like to contribute to Codersee and support the creation of content, you can “buy me a coffee” right here. Have a great day!

The post @JsonProperty vs @JsonAlias in Jackson appeared first on Codersee blog- Kotlin on the backend.

In this short post, I would like to explain the difference between the NullNode and null value when working with Jackson library.

Although these two seem nearly exactly the same, we should be aware of the difference between them and apply appropriate handling in our codebase. Without this knowledge, we may introduce an unexpected behavior to application, which might be hard to track down later.

2. NullNode vs null value

So without further ado, let’s clarify the difference between a NullNode and null:

• the NullNode is a singleton class used to contain an explicit JSON null value
• null value, in terms of dealing with JsonNode, simply means that name/value pair does not exist for a given name

To better visualize this, let’s see the following example:

val mapper = ObjectMapper()
val someObject = mapper.readTree("""
    {
        "id": 1,
        "age": null
    }
""")

val id = someObject.get("id")      // IntNode
val age = someObject.get("age")    // NullNode
val name = someObject.get("name")  // null

As we can see, the age value set explicitly to null results in a NullNode instance being created. On the other hand, a missing name field will lead to a null value on get().

3. Unexpected Behavior Example

With that being said, let’s imagine that we are working with some external REST API in our application and we would like to perform some action based on whether the age is set for user. For the simplicity, we will print the age value to the output in our example.

Given these requirements, we’ve decided to simply check if the value is not null and based on that perform the action:

val age = someObject.get("age")

if(age != null) {
    println("User age is set to $age")
}

Alternatively, we’ve decided to make our Kotlin code even more Kotlin-like with let:

someObject.get("age")
  ?.let { ageValue ->
    println("User age is set to [$ageValue]")
  }

As we can see, the above code will result in totally different behavior depending on whether the age property was set as null explicitly, or not.

To be even more specific, missing value won’t produce any output, whereas "age" : null will print “User age is set to [null].”.

4. Solution

Although the above example is harmless, we should never let that happen and handle appropriately depending on our needs.

One of the possible ways to work with Nullnode and null value in Kotlin could be an additional type check:

if(age != null && age !is NullNode) {
    println("User age is set to $age")
}

Although this is not the most beautiful solution, it makes our code insensitive to the way external API serialized age value.

Alternatively, Jackson library comes with plenty of handy methods, like isXYZ (example: isBoolean(), isLong(), isNumber() etc.):

if (age.isNumber) {
    println("User age is set to $age")
}

This way, we can make sure that our code will be invoked only if the node represents a numeric JSON value.

As I’ve mentioned above, JsonNode class comes with plenty of methods, which can help us to prevent our code from failure and I highly encourage you to check out the documentation.

5. Summary

And that would be all for this short article covering NullNode and null value differences in Jackson. I am more than sure, that this knowledge, will keep you from making mistakes in the future.

Have you ever encountered similar “tricky” situations in your code with Jackson or any other library? If so, could you please share it with others in the comment section or by using a contact form?

Have a great week!

The post What Is The Difference Between Jackson NullNode and Null? appeared first on Codersee blog- Kotlin on the backend.

This time, I would like to show you how to use Retrofit 2 with Kotlin. I will walk you step by step through its features, capabilities and a few obstacles you may encounter when using it.

Let’s start by answering the question: what exactly the Retrofit is? It is a type-safe HTTP client for Android and Java. If you are looking for a library, which will help you to integrate external API in your mobile application, or a back-end service written in Java or Kotlin, then Retrofit is definitely worth a try.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription 🙂

2. Imports

It’s worth mentioning, that Retrofit requires at minimum Java 8+ or Android API 21+, so it won’t be compatible with the legacy codebase.

Moreover, depending on when you are reading this article, the latest stable version can be different and I recommend using the latest one. In my examples, I will be using version: 2.9.0.

2.1. Maven

If you are working with Maven, then you can add it to your project with the following lines:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>(VERSION)</version>
</dependency>

[elementor-template id=”9007393″]

2.2. Gradle

Alternatively, we can use Gradle to fetch the library:

// build.gradle
implementation 'com.squareup.retrofit2:retrofit:<VERSION>'

// build.gradle.kts
implementation("com.squareup.retrofit2:retrofit:<VERSION>")

2.3. Serialization & Deserialization

By default, Retrofit allows us to work only with OkHttp’s RequestBody and ResponseBody objects. Although sometimes it might be sufficient, in most cases we would like to make use of some serialization library when dealing with payloads.

Thankfully, we can achieve that pretty easily by importing desired Converter to our project:

• Gson: com.squareup.retrofit2:converter-gson
• Jackson: com.squareup.retrofit2:converter-jackson
• Moshi: com.squareup.retrofit2:converter-moshi
• Protobuf: com.squareup.retrofit2:converter-protobuf
• Wire: com.squareup.retrofit2:converter-wire
• Simple XML: com.squareup.retrofit2:converter-simplexml
• JAXB: com.squareup.retrofit2:converter-jaxb
• Scalars: com.squareup.retrofit2:converter-scalars

For the purposes of this tutorial, I’ve picked the Jackson library, so we need to add the following to build.gradle.kts file:

implementation("com.squareup.retrofit2:converter-jackson:2.9.0")

3. Retrofit Configuration With Kotlin

As the next step, let’s see how can we configure Retrofit to work with Kotlin.

3.1. Add DTO

Firstly, let’s add an example user DTO to our project:

data class User(
  @JsonProperty("id") val id: Long,
  @JsonProperty("name") val name: String,
  @JsonProperty("age") val age: Int
)

As we can see, this simple class expects the JSON returned by the external API to be in the following format:

{
  "id": 1,
  "name": "Name-1",
  "age": 21
}

3.2. Implement RetrofitClient

Following, let’s add create a RetrofitClient object:

object RetrofitClient {

  private const val BASE_URL = "http://localhost:8090/v1/"

  fun getClient(): Retrofit =
    Retrofit.Builder()
      .baseUrl(BASE_URL)
      .addConverterFactory(JacksonConverterFactory.create())
      .build()
}

The above code is basically responsible for the following:

• setting the base URL for external API
• registering converter factory for objects serialization and deserialization
• creating Retrofit instance

It’s worth mentioning that by default the OkHttpClient will be used underneath, as a factory for calls. Additionally we have to keep in mind that baseUrl has to end in /. Otherwise, the build will fail with IllegalArgumentException.

3.3. Add OkHttpClient Interceptor

As the next step let’s take a look on how to add interceptors to our requests.

If you are wondering why would we need it, then the answer is pretty simple. Oftentimes, when working with external APIs we want to perform some repeatable actions, like:

• adding authorization headers
• logging
• error handling etc.

And to avoid repeating the same code across the whole app, we can simply add an interceptor, which will affect our calls.

With that being said, let’s implement a simple RequestInterceptor:

object RequestInterceptor : Interceptor {
  override fun intercept(chain: Interceptor.Chain): Response {
    val request = chain.request()
    println("Outgoing request to ${request.url()}")
    return chain.proceed(request)
  }
}

As we can see, the above code will print the information about outgoing requests URLs to the output. Later in the article, we will see how to add more interceptors.

But for now, let’s modify the RetrofitClient to make use of a new interceptor:

val okHttpClient = OkHttpClient()
  .newBuilder()
  .addInterceptor(RequestInterceptor)
  .build()

fun getClient(): Retrofit =
  Retrofit.Builder()
    .client(okHttpClient)
    .baseUrl(BASE_URL)
    .addConverterFactory(JacksonConverterFactory.create())
    .build()

4. Handle Responses

As the next step, let’s see how to handle Retrofit responses in our Kotlin codebase.

Let’s start with adding the UserApi interface:

interface UserApi {
  @GET("users")
  fun getUsers(): Call<List<User>>
}

As can be seen, the above function will be used to perform GET requests to http://localhost:8090/v1/users endpoint. In the next chapter we will take a closer look at all supported HTTP methods, but for now, let’s discuss the Call interface.

A Call is basically an invocation of a Retrofit method that sends a request to a web server and returns a response. It can be used synchronously with the execute or asynchronously with enqueue methods. Additionally, each call can be cancelled at any time with cancel.

In this article, we will focus on synchronous calls. Nevertheless, if you would like to learn how to work with Retrofit and Kotlin coroutines, please let me know in the comments section. I will be more than happy to make a continuation for this topic.

4.1. Response Information

With that being said, let’s add a UserService and make use of our configuration:

class UserService {

  private val retrofit = RetrofitClient.getClient()
  private val userApi = retrofit.create(UserApi::class.java)

}

Following, let’s see what information about the response can we obtain with Retrofit:

fun successfulUsersResponse() {
  val usersResponse = userApi.getUsers()
    .execute()

  val successful = usersResponse.isSuccessful
  val httpStatusCode = usersResponse.code()
  val httpStatusMessage = usersResponse.message()

}

Basically, the execute() method returns the Response<T>, which lets us obtain info about the… response 🙂

Let’s have a close look at each line:

val successful = usersResponse.isSuccessful

The isSuccessful returns true, if the HTTP code is in the range [200…300]. It is a really good choice when we don’t care about the specific codes.

val httpStatusCode = usersResponse.code()

On the other hand, the code() method returns the exact Integer value of the response HTTP status code.

val httpStatusMessage = usersResponse.message()

Finally, the message(), might be useful, if we would like to get the HTTP status message, like OK.

4.2. Successful Response Body

Following, let’s see how easily we can obtain the response body:

val body: List<User>? = usersResponse.body()

Nevertheless, please keep in mind that Retrofit body() method may return null, so we should handle it properly with Kotlin.

4.3. Retrofit Error Body

Life would be much easier, if there were no errors.

Nevertheless, they happen, and it’s better to get more information about them:

val errorBody: ResponseBody? = usersResponse.errorBody()

The rule is pretty simple here: when the response is successful, the body is populated. Oherwise, the errorBody field is not null. It’s worth mentioning here that Retrofit errorBody() method is not generic and we have to handle payload manually.

Let’s see how can we achieve that with Jackson library. Firstly, let’s add the ErrorResponse data class:

data class ErrorResponse(
  @JsonProperty("message") val message: String
)

Following, let’s use the ObjectMapper:

val errorBody: ResponseBody? = usersResponse.errorBody()

val mapper = ObjectMapper()

val mappedBody: ErrorResponse? = errorBody?.let { notNullErrorBody ->
  mapper.readValue(notNullErrorBody.toString(), ErrorResponse::class.java)
}

This way, when Retrofit populates the errorBody property, we use Kotlin’s let function to deserialize payload into the ErrorResponse instance.

4.4. Read Response Headers

Finally, let’s take a look at response headers, because sometimes they can contain useful information:

val headers = usersResponse.headers()
val customHeaderValue = headers["custom-header"]

As we can see, with these two lines we can simply obtain the value of the custom-header returned from external API.

5. HTTP Methods

So far, we’ve learned how to handle various responses, but GET is not the only option, so let’s have a look at other possibilities.

Basically, Retrofit comes with 8 built-in annotations: HTTP, GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD. Although the choice will depend on the endpoint we query, I would like to take a closer look at @HEAD and @HTTP annotations.

5.1. Retrofit @HEAD

Let’s start with the @HEAD annotation:

@HEAD("users")
fun headUsers(): Call<Void>

As we can see, the return type here is Void– and it must be always be. Otherwise, Retrofit will throw IllegalArgumentException with: HEAD method must use Void as response type message.

5.2. Retrofit @HTTP and @DELETE

The @HTTP annotation is pretty interesting, as well. It lets us use a custom HTTP verb for a request.

Let’s see an example:

@GET("users")
fun getUsers(): Call<List<User>>

@HTTP(method = "GET", path = "users")
fun httpUsers(): Call<List<User>>

Basically, both functions work exactly the same and in real-life scenarios we will hardly ever use the second option. Given that, why should we care about it?

Well, let’s see the following snippet:

@DELETE("users")
fun failingDeleteUser(@Body user: User): Call<User>

As the name of the function suggests, it will fail. And to be more specific, it will fail with the following message: Non-body HTTP method cannot contain @Body.

In such a case, the @HTTP annotation allows us to set hasBody flag, which we can use to perform the DELETE request with payload:

@HTTP(method = "DELETE", path = "users", hasBody = true)
fun workingDeleteUser(@Body user: User): Call<User>

6. URL Manipulation

Until now, we saw how to use a hard-coded URLs and sometimes it will be sufficient. Nevertheless, in real-life scenarios we will have to specify additional query parameters, or path variables sooner or later.

6.1. Use Absolute Path

As the first step, let’s see how can we instruct Retrofit to use a custom, absolute path in our Kotlin interface:

@GET("http://localhost:8090/v3/users")
fun getUsersV3(): Call<List<User>>

This might be really helpful, when we would like to query another API, or just another version of the same provider without the need to set up next interface. Just like above handler will perform a GET request to V3 endpoint.

6.2. Dynamic URL With @Url

On the other hand, Retrofit has the possibility to specify the URL on method invocation:

@GET
fun getUsersDynamic(@Url url: String): Call<List<User>>

This way, we have the possibility to specify desired URL as an argument. Nevertheles, it’s a good time to have a look on how URLs are resolved in Retrofit:

• userApi.getUsersDynamic(“users”) – will be resolved to http://localhost:8090/v1/users
• userApi.getUsersDynamic(“/users”) – will be treated as http://localhost:8090/users
• userApi.getUsersDynamic(“http://localhost:8090/v3/users”) – just like in the previous example, will use the provided, absolute path

6.3. Use Path Variable

Following, let’s see how to make use of replacement blocks:

@GET("users/{userId}")
fun getUserById(@Path("userId") userId: Int): Call<User>

As we can see, we can specify the user id when invoking the function. So the following call: userApi.getUserById(99), will result in GET request to http://localhost:8090/v1/users/99.

6.4. Add Query Parameters

Another common way of exchanging information are query parameters:

@GET("users?sort_order=asc")
fun getUsersStaticQueryParam(): Call<List<User>>

As can be seen, we use a static sort_order query parameter. Although I discourage this approach I wanted to show that it is possible when working with Retrofit.

To get a better control over the sent parameters, we can use a @Query annotation:

@GET("users")
fun getUsersDynamicQueryParam(@Query("sort_order") order: String): Call<List<User>>

This way, our function becomes much more generic. Calling it with the “desc” argument, will result in sort_order=desc in our URL.

As the last one, let’s see how can we add multiple parameters with @QueryMap:

@GET("users")
fun getUsersDynamicQueryMap(@QueryMap parameters: Map<String, String>): Call<List<User>>

This way, when the API requires multiple query parameters, we can encapsulate them in a map. Without that we would end up with a function taking plenty of arguments, which would affect code readability.

So, the following code:

userApi.getUsersDynamicQueryMap(
  mapOf(
    "order" to "asc",
    "name" to "some"
  )
)

Will be translated to: http://localhost:8090/v1/users?order=asc&name=some

7. Request Headers

Headers are inseparable part of every REST communication. Oftentimes, we will have to send additional information, like Content-Type, or Authorization. In this chapter we will learn a few possibilities Retrofit gives us to work with them.

7.1. Static Headers

Let’s start with a single header:

@Headers("User-Agent: codersee-application")
@GET("users")
fun getUsersSingleStaticHeader(): Call<List<User>>

Similarly, we can append multiple headers to the request:

@Headers(
  value = [
    "User-Agent: codersee-application",
    "Custom-Header: my-custom-header"
])
@GET("users")
fun getUsersMultipleStaticHeaders(): Call<List<User>>

7.2. Dynamic Headers

Although the two above will be useful in some cases, oftentimes we will need to pass a dynamic value for a header, like Authorization for instance. To achieve that, we can use a @Header annotation:

@GET("users")
fun getUsersDynamicHeader(@Header("Authorization") token: String): Call<List<User>>

Just like with @Query annotation, Retrofit allows us to pass multiple headers in a Map form with @HeaderMap:

@GET("users")
fun getUsersHeaderMap(@HeaderMap headers: Map<String, String>): Call<List<User>>

7.3. Authorization Interceptor

As the next step, I would like to show you how to make life easier and extract logic responsible for tokens generation to Retrofit config. This is way, each request to the given API will contain a generated token and we won’t need to add it each time.

Let’s start with adding a Kotlin object called AuthorizationInterceptor:

object AuthorizationInterceptor : Interceptor {
  override fun intercept(chain: Interceptor.Chain): Response {
    val requestWithHeader = chain.request()
      .newBuilder()
      .header(
        "Authorization", UUID.randomUUID().toString()
      ).build()
    return chain.proceed(requestWithHeader)
  }
}

Just like in the chapter number 3, we extend the Interceptor interface, but this time we additionally call a newBuilder() on the request instance. With that being done, we can modify its behavior, like add headers or tags (and I highly encourage you to check all the possible options). In your project, the UUID.randomUUID().toString() would be replaced with a call to another service, or logic responsible for generating real tokens.

As the last step, we have to add it to the OkHttpClient:

val okHttpClient = OkHttpClient()
  .newBuilder()
  .addInterceptor(AuthorizationInterceptor)
  .addInterceptor(RequestInterceptor)
  .build()

This way, each request will be enhanced with the Authorization header.

8. Request Body

Finally, we can learn how to attach a payload to Retrofit requests.

8.1. Send Object as JSON

Let’s start with the most popular way of sending data- a JSON payload:

@POST("users")
fun postUsersWithPayload(@Body user: User): Call<User>

With the @Body annotation, we can pass a User instance, which will be then serialized using configured Retrofit converter (Jackson in our case).

8.2. Retrofit URL-Encoded Form

On the other hand, if we would like to send data in a URL-Encoded Form, we can use the @FormUrlEncoded along with @Field:

@FormUrlEncoded
@POST("users")
fun postUsersFormUrlEncoded(@Field("field_one") fieldOne: String): Call<User>

8.3. Multipart

Lastly, to send the data as a HTTP multipart request, we can use @Multipart on a function with @Part on each part send to the external REST API:

@Multipart
@POST("users")
fun postUsersMultipart(@Part("something") partOne: RequestBody): Call<User>

9. Retrofit With Kotlin Summary

And that would be all for this article on Retrofit with Kotlin. We’ve learned together almost everything you will need to know when working on your very own project. As always, you can find the source code in this GitHub Repository.

If you would like to learn a bit more, then check out the continuation of this article, in which I show how to use Retrofit 2 with Kotlin Coroutines. On the other hand, if you would like to combine this knowledge and learn how to create back-end services with Kotlin, you will find step-by-step tutorials in the Ktor category.

I hope you enjoyed this article and will be really happy if you would like to give me feedback in the comments section.

The post Retrofit With Kotlin- The Ultimate Guide appeared first on Codersee blog- Kotlin on the backend.