You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
4. UnknownError: Represents every other kind of error which can not be classified as an API error or a network problem (eg JSON deserialization exceptions)
18
19
19
-
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.
20
-
The response type represents the Java/Kotlin representation of your API network response. The error type represents your API's error response.
20
+
It is generic on two types: a response (`S`), and an error (`E`). The response type is your Java/Kotlin representation of the API response, while the error type represents the error response sent by the API.
21
21
22
+
## Usage
22
23
23
-
#### Usage
24
+
- Suppose you have an API that returns the following response if the request is successful:
24
25
25
-
Suppose you have an API that returns the following response if the request is successful:
26
+
_Successful Response_
26
27
27
-
*Successful Response*
28
-
```json
29
-
{
28
+
```json
29
+
{
30
30
"name": "John doe",
31
31
"age": 21
32
-
}
33
-
```
34
-
35
-
And here's the response when the request was unsuccessful:
36
-
37
-
*Error Response*
38
-
```json
39
-
{
40
-
"message": "The requested person was not found"
41
-
}
42
-
```
32
+
}
33
+
```
43
34
44
-
You can create two data classes to model the these responses:
35
+
- And here's the response when the request was unsuccessful:
45
36
46
-
```kotlin
47
-
data classPersonResponse(valname:String, valage:Int)
48
-
data classErrorResponse(valmessage:String)
49
-
```
37
+
_Error Response_
50
38
51
-
You may then write your API service as:
39
+
```json
40
+
{
41
+
"message": "The requested person was not found"
42
+
}
43
+
```
44
+
45
+
- You can create two data classes to model the these responses:
46
+
47
+
```kotlin
48
+
data classPersonResponse(valname:String, valage:Int)
- You can also use the included utility function `executeWithRetry` to automatically retry your network requests if they result in `NetworkResponse.NetworkError`
- There's also an overloaded invoke operator on the NetworkResponse class which returns the success body if the request was successful, or null otherwise
71
118
72
-
Then consume the API as follows:
73
-
74
-
```kotlin
75
-
// Repository.kt
76
-
77
-
suspendfungetPerson() {
78
-
val person = apiService.getPerson().await()
79
-
// or if you use suspending functions,
80
-
val person = runBlocking { apiService.getPerson() }
81
-
82
-
when (person) {
83
-
isNetworkResponse.Success-> {
84
-
// Handle Success
85
-
}
86
-
isNetworkResponse.ServerError-> {
87
-
// Handle Server Error
88
-
}
89
-
isNetworkResponse.NetworkError-> {
90
-
// Handle Network Error
91
-
}
92
-
}
93
-
}
94
-
```
119
+
```kotlin
120
+
val usersResponse = usersRepo.getUsers().await()
121
+
println(usersResponse() ?:"No users were found")
122
+
```
95
123
96
-
You can also use the included utility function `executeWithRetry` to automatically retry your network requests if they result in `NetworkResponse.NetworkError`
97
-
```kotlin
98
-
suspendfungetPerson() {
99
-
val response = executeWithRetry(times =5) {
100
-
apiService.getPerson.await()
101
-
}
102
-
103
-
// or with suspending functions
104
-
val response = executeWithRetry(times =5) {
105
-
apiService.getPerson()
106
-
}
107
-
108
-
// Then handle the response
109
-
}
110
-
```
124
+
- Some API responses convey information through headers only, and contain empty bodies. Such endpoints must be used with `Unit` as their success type.
111
125
112
-
There's also an overloaded invoke operator on the NetworkResponse class so that its success body can be accessed directly.
113
-
```kotlin
114
-
val usersResponse = usersRepo.getUsers().await()
115
-
println(usersResponse() ?:"No users were found") // Returns users if response is successful, or null otherwise
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.
122
-
For any other unexpected situation, you probably want to crash your application so that you can take a look at what's going on.
133
+
## Benefits
123
134
124
-
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.
125
-
It is built on top of coroutines support, so asynchronous network requests become a lot easier too!
135
+
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, and extract meaningful information from them too!
126
136
127
-
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.
128
-
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.
137
+
-`NetworkResponseAdapter` provides a much cleaner solution than Retrofit's built in `Call` type for dealing with errors.`Call` throws an exception on any kind of an error, leaving it up to you to catch it and parse it manually to figure out what went wrong. `NetworkResponseAdapter` does all of that for you and returns the result in an easily consumable `NetworkResponse` subtype.
129
138
130
-
However, because a lot of things are treated as errorsin the Rx Adapter, retrying becomes as easy as dropping the `retry()` operator in the middle of the stream.
139
+
- The RxJava retrofit adapter treats non 2xx response codes as errors, which seems silly in the context of Rx where errors terminate streams. Also, just like the `Call<T>` type, it makes you deal with all types of errors in an `onError` callback, where you have to manually parse it to find out exactly what went wrong.
131
140
132
-
While the solution provided by this library is not as convenient as that, you can take a look at the `executeWithRetry` utility method.
133
-
It is a higher order function which can retry your network requests if they fail.
141
+
- Using the `Response` class provided by Retrofit is cumbersome, as you have to manually parse error bodies with it.
134
142
135
-
####Installation
143
+
## Installation
136
144
137
145
Add the Jitpack repository to your list of repositories:
0 commit comments