Oversimplified network call using Retrofit, LiveData, Kotlin Coroutines and DSL
When you build an app that has to deal with network calls, you almost end up writing the same boilerplate code in order to perform that. What if we try to automate and reduce the amount of code we need to write for a network call ?
What do we need ?
We don’t have to argue about it, we are all using Retrofit. If you don’t, go and start using it. But, in this post we are going to use Retrofit with Kotlin Coroutines Adapter made by the all mighty Jake Wharton, LiveData of Android Architecture components and build a small Kotlin DSL. We will also use a bit of Kotlin generics. We assume that you already know all those concepts a little bit. Otherwise, you can check the references at the end of this post.
The basics
Let’s assume we are getting a list of Posts from server. This is how we are going to do it.
The endpoint returns a Deferred<*> which is the type returned by an async coroutine in Kotlin. But most importantly, you need to know what the PostResponse looks like.
The BaseApiResponse is the base class that all the api responses inherit from. We do that because, as you can see, every response coming from the server has a custom status and message fields and some random data. This is just an API design choice, yours could be different.
Kotlin Coroutines Adapter for Retrofit
As we mentioned before, when you are using Coroutines adapter, Retrofit sends you back a Deferred<Response<*>>. From that you can use the await() function to get the value.
But to keep things simple we are going to use this project in the way we perform network calls with retrofit coroutines adapter. By doing that, this is how we are going to perform every network call in our app.
On this code snippet, you may have noticed two things
awaitResult(): an extension function of Deferred. It is the way the you get a Result object. The Result object unwraps the response from the server.
getOrThrow(): which is a function of Result that either get the response when the HTTP request succeed or throws an exception when the HTTP request failed. That means you need to put the above code within a try/catch block.
LiveData to the rescue
It’s 2018, and all of us should have given AAC a try already. Then you already know what a LiveData is and how helpful it can be. It doesn’t matter if you are following any specific Architecture here. Be it MVP or MVVM or whatever we don’t care about that because LiveData can still be used in all these cases.
What we want to do is to let our Repository send back a LiveData that we can track the state by using the Resource class. The Resource class lets us define 3 state on the data it is holding. These states are: loading, success, error. You can check the sample to learn more.
So before we perform the network call, we set the LiveData resource state to LOADING. When the network request succeed we set the LiveData Resource to SUCCESS and when there is an Http error or any other error, we set it to ERROR.
By putting all this information together, this is what we got
This code is pretty simple to understand. We use withContext() because we want to set the value of the result LiveData in the main thread. But you could definitely use postValue() method if you want. Because a launch coroutine is by default running on the CommonPool context, withContext() allows you to switch to another execution context in your coroutine. Here we switch to the UI coroutine Context which represents the Android main thread.
It looks nice though! So what’s the point ?
Well, if you look at the code above, even though it looks simple, there is still a problem. Every time you gonna need to make a network call, you will do the same damn thing. Create a LiveData object, set the value to Resource.loading, get an instance of the retrofit service client, make the network call and update the value of the LiveData depending on the Result of your network request.
That is kind of boring don’t you think ? And there is for sure some boilerplate code that you can get rid of. Actually, the only thing that really change is the network call itself. What if we do something about that ?
DSL comes to the rescue
Kotlin is a modern and wonderful language which comes with several features that help us bring more and more consistency in our code. One of these features is the ability to create DSLs. We won’t be going through the basics of DSLs here, there are already some good posts about it. But the goal here is to simplify the way we make network calls by creating a whole new syntax.
To write a very basic DSL, you need to properly understand these 3 Kotlin concepts:
- Use of lambdas outside of method parentheses
- Lambdas with receivers (definitely the most important)
- Extension functions
By analysing the last portion of code above. We can conclude that in order to perform any network call in this way, there will be only 3 details that will change:
- The function return type
- The Retrofit endpoint function
- The response object returned by the endpoint function.
So if we want to change that, we just need to tell our DSL the things we want him to change and the rest will stay unchanged. Then what if our network call looked like this:
Looks cool right ? But how can we achieve this ?
We can start by creating the networkCall() function that will be generic with two type parameters. One for the endpoint response, and the other for the actual data returned by the repository class.
You will notice a class called CallHandler. This class is actually the one that really makes all the magic happen. As you can see in the declaration of the function, we have a block parameter that is actually an extension function of CallHandler. CallHandler is also a generic class with same type parameter as the networkCall function and has a function called makeCall(). Now let see what CallHandler class looks like.
There is only one thing that will look strange to you in this code: DataResponse. We added a new Class called DataResponse so we can easily get the data returned by the endpoint response. Remember, earlier we said that the endpoint is returning a Deferred<Response<PostResponse>>. So PostResponse is what the server sends back to us. Also, we said that in our api design, every response returned by the server always have a status, a message and some data. We are more interested by the data but the data could change type from one response to another. So in this very generic method, we need a way do get the data whatever their type and put it as value of our result LiveData. This is why we created the DataResponse interface that will be inherited by every Response class used in the scope of our DSL.
Then the PostResponse gonna look like this
And we are done! With everything set up we can definitely make any network call using our DSL in a very simple way just like this:
You just change the Response, the data, the endpoint function and you’re good.
Conclusion
DSL in Kotlin offers a lot of possibilities that could just simply change the way we look at things and sets our mind in a continuous need of code simplification.
“Simplicity is the best sophistication” — Leonardo da Vinci
Thank you for reading. Hope you enjoyed this oversimplification process. Try it and let me know your thoughts in the comments. Looking forward to see how much you guys can improve this.
Update:
Source code. https://github.com/rygelouv/networkcall-sample
References
We highly recommend you to check these resources if you want to properly understand what we did here.
