NetworkResponseAdapter: A Kotlin repository from rishabh115

NetworkResponse Retrofit adapter

A call adapter that handles errors as a part of state

This library provides a Retrofit call adapter for wrapping your API responses in a NetworkResponse class using Coroutines.

This library uses OkHttp 4, which requires Android API version 21+ and Java 8+

Network Response

Network response is a Kotlin sealed class with the following three states:

Success: Used to represent successful responses (2xx response codes, non empty response bodies)
ServerError: Used to represent Server errors
NetworkError: Used to represent connectivity errors

The sealed class is generic on two types: The response type, and an error type. The response type is your Java/Kotlin representation of the API response, while the error type represents the error response sent by the API server. The response type represents the Java/Kotlin representation of your API network response. The error type represents your API's error response.

Usage

Suppose you have an API that returns the following response if the request is successful:

Successful Response

{
    "name": "John doe",
    "age": 21
}

And here's the response when the request was unsuccessful:

Error Response

{
    "message": "The requested person was not found"
}

You can create two data classes to model the these responses:

data class PersonResponse(val name: String, val age: Int)
data class ErrorResponse(val message: String)

You may then write your API service as:

// APIService.kt

@GET("<api-url>")
fun getPerson(): Deferred<NetworkResponse<PersonResponse, ErrorResponse>>

// or if you want to use Suspending functions
@GET("<api-url>")
suspend fun getPerson(): NetworkResponse<PersonResponse, ErrorResponse>>

Make sure to add this call adapter factory when building your Retrofit instance:

Retrofit.Builder()
    .addCallAdapterFactory(NetworkResponseAdapterFactory())
    .build()

Then consume the API as follows:

// Repository.kt

suspend fun getPerson() {
    val person = apiService.getPerson().await()
    // or if you use suspending functions,
    val person = runBlocking { apiService.getPerson() }

    when (person) {
        is NetworkResponse.Success -> {
            // Handle Success
        }
        is NetworkResponse.ServerError -> { 
            // Handle Server Error 
        }
        is NetworkResponse.NetworkError -> {
            // Handle Network Error
        }
    }
}

You can also use the included utility function executeWithRetry to automatically retry your network requests if they result in NetworkResponse.NetworkError

suspend fun getPerson() {
    val response = executeWithRetry(times = 5) {
        apiService.getPerson.await()
    }
    
    // or with suspending functions
    val response = executeWithRetry(times = 5) {
        apiService.getPerson()
    }

    // Then handle the response
}

There's also an overloaded invoke operator on the NetworkResponse class so that its success body can be accessed directly.

val usersResponse = usersRepo.getUsers().await() 
println(usersResponse() ?: "No users were found") // Returns users if response is successful, or null otherwise

Why?

Modelling errors as a part of your state is a recommended practice. This library helps you deal with scenarios where you can successfully recover from errors. Server errors and Connectivity problems can be easily dealt with. For any other unexpected situation, you probably want to crash your application so that you can take a look at what's going on.

The NetworkResponse adapter provides a much cleaner solution than Retrofit's built in Call type, because it models errors as a sealed class and does not force you to think in terms of callbacks. It is built on top of coroutines support, so asynchronous network requests become a lot easier too!

The RxJava retrofit adapter treats non 2xx error codes as errors too, which seems silly. An error in an Rx stream should be something from which it is difficult to recover. This is not the best way to deal with errors from an API response, because they can contain meaningful information too. They should not be specifically dealt with in onError blocks.

However, because a lot of things are treated as errors in the Rx Adapter, retrying becomes as easy as dropping the retry() operator in the middle of the stream.

While the solution provided by this library is not as convenient as that, you can take a look at the executeWithRetry utility method. It is a higher order function which can retry your network requests if they fail.

Installation

Add the Jitpack repository to your list of repositories:

allprojects {
  repositories {
    maven { url 'https://jitpack.io' }
  }
}

And then add the dependency in your gradle file:

dependencies {
  implementation "com.github.haroldadmin:NetworkResponseAdapter:(latest-version)"
}

License