v1.x.y

Fuel - Documentation
Search…
README
Core
Support
Deserialization
Kotlinx-Serialization
Moshi
Legacy
v1.x.y
​​
​ ​
​ ​
​ ​
​​
The easiest HTTP networking library for Kotlin/Android.
Features
Support basic HTTP GET/POST/PUT/DELETE/HEAD/PATCH in a fluent style interface
Support both asynchronous and blocking requests
Download file
Upload file (multipart/form-data)
Cancel in-flight request
Request timeout
Configuration manager by using FuelManager
Debug log / cUrl log
Support response deserialization into plain old object (both Kotlin & Java)
Automatically invoke handler on Android Main Thread when using Android Module
Special test mode for easier testing
Support for reactive programming via RxJava 2.x and Project Reactor 3.x
Google Components LiveData support
Built-in object serialization module (kotlinx-serialization, Gson, Jackson, Moshi, Forge) :sparkles:
Support Kotlin's Coroutines module
API Routing
Installation
There are 2 versions of Fuel build against different Kotlin Versions
​​
​​
Kotlin - 1.2.71
Coroutine - 0.23.3
​​
​​
Kotlin - 1.3.0-rc-146
Coroutine - 0.30.1-eap13
Dependency - fuel
​Result - The modelling for success/failure of operations in Kotlin
Dependency - fuel-android
​Android SDK - Android SDK
Min SDK: 19 
Dependency - fuel-livedata
​Live Data - Android Architecture Components - LiveData
Dependency - fuel-rxjava
​RxJava - RxJava – Reactive Extensions for the JVM
Dependency - fuel-coroutines
​Coroutines - Kotlin Coroutines - Library support for Kotlin coroutines
Dependency - fuel-kotlinx-serialization
​Kotlinx Serialization - Kotlinx Serialization - Kotlin cross-platform / multi-format serialization
Dependency - fuel-gson
​Gson - Gson - A Java serialization/deserialization library to convert Java Objects into JSON and back
Dependency - fuel-jackson
​Jackson - Jackson - The JSON library for Java
Dependency - fuel-moshi
​Moshi - Moshi - A modern JSON library for Android and Java
Dependency - fuel-forge
​Forge - Forge - Functional style JSON parsing written in Kotlin
Dependency - fuel-reactor
​Project Reactor - Project Reactor - Implementation of Reactive Streams standard
Gradle
1
repositories {
2
    jcenter()
3
}
4
​
5
dependencies {
6
    compile 'com.github.kittinunf.fuel:fuel:<latest-version>' //for JVM
7
    compile 'com.github.kittinunf.fuel:fuel-android:<latest-version>' //for Android
8
    compile 'com.github.kittinunf.fuel:fuel-livedata:<latest-version>' //for LiveData support
9
    compile 'com.github.kittinunf.fuel:fuel-rxjava:<latest-version>' //for RxJava support
10
    compile 'com.github.kittinunf.fuel:fuel-coroutines:<latest-version>' //for Kotlin Coroutines support
11
    compile 'com.github.kittinunf.fuel:fuel-gson:<latest-version>' //for Gson support
12
    compile 'com.github.kittinunf.fuel:fuel-jackson:<latest-version>' //for Jackson support
13
    compile 'com.github.kittinunf.fuel:fuel-moshi:<latest-version>' //for Moshi support
14
    compile 'com.github.kittinunf.fuel:fuel-forge:<latest-version>' //for Forge support
15
    compile 'com.github.kittinunf.fuel:fuel-reactor:<latest-version>' //for Reactor support
16
}
Copied!
Sample
There are two samples, one is in Kotlin and another one in Java.
Quick Glance Usage
Async mode
Kotlin
```kotlin
//an extension over string (support GET, PUT, POST, DELETE with httpGet(), httpPut(), httpPost(), httpDelete())
"https://httpbin.org/get".httpGet().responseString { request, response, result ->
//do something with response
when (result) {
  is Result.Failure -> {
1
val ex = result.getException()
Copied!
  }
  is Result.Success -> {
1
val data = result.get()
Copied!
  }
}
}
//if we set baseURL beforehand, simply use relativePath FuelManager.instance.basePath = "https://httpbin.org" "/get".httpGet().responseString { request, response, result -> //make a GET to https://httpbin.org/get and do something with response val (data, error) = result if (error == null) { //do something when success } else { //error handling } }
//if you prefer this a little longer way, you can always do //get Fuel.get("https://httpbin.org/get").responseString { request, response, result -> //do something with response result.fold({ d -> //do something with data }, { err -> //do something with error }) }
1
* Java
2
```java
3
//get
4
Fuel.get("https://httpbin.org/get", params).responseString(new Handler<String>() {
5
    @Override
6
    public void failure(Request request, Response response, FuelError error) {
7
        //do something when it is failure
8
    }
9
​
10
    @Override
11
    public void success(Request request, Response response, String data) {
12
        //do something when it is successful
13
    }
14
});
Copied!
Blocking mode
You can also wait for the response. It returns the same parameters as the async version, but it blocks the thread. It supports all the features of the async version.
Kotlin
1
val (request, response, result) = "https://httpbin.org/get".httpGet().responseString() // result is Result<String, FuelError>
Copied!
Java
```java try { Triple data = Fuel.get("https://www.google.com").responseString(); Request request = data.getFirst(); Response response = data.getSecond(); Result text = data.getThird(); } catch (Exception networkError) {
}
1
## Detail Usage
2
​
3
### GET
4
​
5
```kotlin
6
Fuel.get("https://httpbin.org/get").response { request, response, result ->
7
    println(request)
8
    println(response)
9
    val (bytes, error) = result
10
    if (bytes != null) {
11
        println(bytes)
12
    }
13
}
Copied!
Response Handling
Result
​Result is a functional style data structure that represents data that contains result of Success or Failure but not both. It represents the result of an action that can be success (with result) or error.
Working with result is easy. You could fold, destructure as because it is just a data class or do a simple when checking whether it is Success or Failure.
Response
1
fun response(handler: (Request, Response, Result<ByteArray, FuelError>) -> Unit)
Copied!
Response in String
1
fun responseString(handler: (Request, Response, Result<String, FuelError>) -> Unit)
Copied!
Response in Json
requires the android extension​
1
fun responseJson(handler: (Request, Response, Result<Json, FuelError>) -> Unit)
2
​
3
val jsonObject = json.obj() //JSONObject
4
val jsonArray = json.array() //JSONArray
Copied!
Response in T (object)
1
fun <T> responseObject(deserializer: ResponseDeserializable<T>, handler: (Request, Response, Result<T, FuelError>) -> Unit)
Copied!
POST
1
Fuel.post("https://httpbin.org/post").response { request, response, result ->
2
}
3
​
4
// JSON body from string (automatically sets application/json as Content-Type)
5
Fuel.post("https://httpbin.org/post")
6
    .jsonBody("{ \"foo\" : \"bar\" }")
7
    .response { request, response, result -> }
8
​
9
// Body from a generic string
10
Fuel.post("https://httpbin.org/post")
11
    .header(Headers.CONTENT_TYPE, "text/plain")
12
    .body("my body is plain")
13
    .response { request, response, result -> }
14
​
15
// Body from a file
16
Fuel.post("https://httpbin.org/post")
17
    .header(Headers.CONTENT_TYPE, "text/plain")
18
    .body(File("lipsum.txt"))
19
    .response { request, response, result -> }
20
​
21
// Body from a generic stream
22
val stream = ByteArrayInputStream("source-string-from-string".toByteArray())
23
Fuel.post("https://httpbin.org/post")
24
    .header(Headers.CONTENT_TYPE, "text/plain")
25
    .body(stream)
26
    .response { request, response, result -> }
Copied!
PUT
1
Fuel.put("https://httpbin.org/put")
2
    .response { request, response, result -> }
3
​
4
// Supports all the body methods, like POST requests
Copied!
DELETE
1
Fuel.delete("https://httpbin.org/delete")
2
    .response { request, response, result -> }
3
​
4
// Supports all the body methods, like POST requests
Copied!
HEAD
1
Fuel.head("https://httpbin.org/get")
2
    .response { request, response, result -> /* request body is empty */ }
Copied!
PATCH
The default client is HttpClient which is a thin wrapper over java.net.HttpUrlConnection. java.net.HttpUrlConnection does not support a [PATCH](https://download.java.net/jdk7/archive/b123/docs/api/java/net/HttpURLConnection.html#setRequestMethod(java.lang.String)) method. HttpClient converts PATCH requests to a POST request and adds a X-HTTP-Method-Override: PATCH header. While this is a semi-standard industry practice not all APIs are configured to accept this header by default.
1
Fuel.patch("https://httpbin.org/patch").response { request, response, result -> }
2
​
3
// Supports all the body methods, like POST requests
Copied!
CONNECT
Connect is not supported by the Java JVM via the regular HTTP clients, and is therefore not supported.
OPTIONS
There are no convenience methods for making an OPTIONS request, but you can still make one directly:
1
Fuel.request(Method.OPTIONS, "https://httpbin.org/anything")
2
    .response { request, response, result -> }
Copied!
TRACE
There are no convenience methods for making an TRACE request, but you can still make one directly:
1
Fuel.request(Method.TRACE, "https://httpbin.org/anything")
2
    .response { request, response, result -> }
Copied!
Debug Logging
Use toString() method to inspect requests
1
val request = Fuel.get("https://httpbin.org/get", parameters = listOf("key" to "value"))
2
println(request)
3
​
4
// --> GET (https://httpbin.org/get?key=value)
5
//    Body : (empty)
6
//    Headers : (2)
7
//    Accept-Encoding : compress;q=0.5, gzip;q=1.0
8
//    Device : Android
Copied!
Use toString() method to inspect responses
1
val (_, response, _) = Fuel.get("https://httpbin.org/get", parameters = listOf("key" to "value")).response()
2
println(response)
3
// <-- 200 (https://httpbin.org/get?key=value)
4
//    Body : (empty)
Copied!
Also support cUrl string to Log request, make it very easy to cUrl on command line
1
val request = Fuel.post("https://httpbin.org/post", parameters = listOf("foo" to "foo", "bar" to "bar", "key" to "value"))
2
println(request.cUrlString())
Copied!
1
curl -i -X POST -d "foo=foo&bar=bar&key=value" -H "Accept-Encoding:compress;q=0.5, gzip;q=1.0" -H "Device:Android" -H "Content-Type:application/x-www-form-urlencoded" "https://httpbin.org/post"
Copied!
Parameter Support
URL encoded style for GET & DELETE request
1
Fuel.get("https://httpbin.org/get", listOf("foo" to "foo", "bar" to "bar"))
2
    .response { request, response, result -> }
3
// resolve to https://httpbin.org/get?foo=foo&bar=bar
4
​
5
Fuel.delete("https://httpbin.org/delete", listOf("foo" to "foo", "bar" to "bar"))
6
    .response { request, response, result -> }
7
// resolve to https://httpbin.org/delete?foo=foo&bar=bar
Copied!
Array support for GET requests
1
Fuel.get("https://httpbin.org/get", listOf("foo" to "foo", "dwarf" to  arrayOf("grumpy","happy","sleepy","dopey")))
2
    .response { request, response, result -> }
3
// resolve to  https://httpbin.org/get?foo=foo&dwarf[]=grumpy&dwarf[]=happy&dwarf[]=sleepy&dwarf[]=dopey
Copied!
Support x-www-form-urlencoded for PUT & POST
1
Fuel.post("https://httpbin.org/post", listOf("foo" to "foo", "bar" to "bar"))
2
    .response { request, response, result -> }
3
// Body : "foo=foo&bar=bar"
4
​
5
Fuel.put("https://httpbin.org/put", listOf("foo" to "foo", "bar" to "bar"))
6
    .response { request, response, result -> }
7
// Body : "foo=foo&bar=bar"
Copied!
Set request's timeout and read timeout
Default timeout for a request is 15000 milliseconds. Default read timeout for a request is 15000 milliseconds.
Kotlin
```kotlin
val timeout = 5000 // 5000 milliseconds = 5 seconds.
val timeoutRead = 60000 // 60000 milliseconds = 1 minute.
Fuel.get("https://httpbin.org/get") .timeout(timeout) .timeoutRead(timeoutRead) .responseString { request, response, result -> }
1
* Java
2
```java
3
int timeout = 5000 // 5000 milliseconds = 5 seconds.
4
int timeoutRead = 60000 // 60000 milliseconds = 1 minute.
5
Fuel.get("https://httpbin.org/get", params).timeout(timeout).timeoutRead(timeoutRead).responseString(new Handler<String>() {
6
    @Override
7
    public void failure(Request request, Response response, FuelError error) {
8
        //do something when it is failure
9
    }
10
​
11
    @Override
12
    public void success(Request request, Response response, String data) {
13
        //do something when it is successful
14
    }
15
});
Copied!
Download with or without progress handler
1
Fuel.download("https://httpbin.org/bytes/32768")
2
    .destination { response, url -> File.createTempFile("temp", ".tmp") }
3
    .response { req, res, result -> }
4
​
5
Fuel.download("https://httpbin.org/bytes/32768")
6
    .destination { response, url -> File.createTempFile("temp", ".tmp") }
7
    .progress { readBytes, totalBytes ->
8
        val progress = readBytes.toFloat() / totalBytes.toFloat() * 100
9
        println("Bytes downloaded $readBytes / $totalBytes ($progress %)")
10
    }
11
    .response { req, res, result -> }
Copied!
Upload with or without progress handler
1
Fuel.upload("/post")
2
    .source { request, url -> File.createTempFile("temp", ".tmp") }
3
    .responseString { request, response, result -> }
4
​
5
// By default upload use Method.POST, unless it is specified as something else
6
Fuel.upload("/put", Method.PUT)
7
    .source { request, url -> File.createTempFile("temp", ".tmp") }
8
    .responseString { request, response, result -> }
9
​
10
// Upload with multiple files
11
Fuel.upload("/post")
12
    .sources { request, url ->
13
        listOf(
14
            File.createTempFile("temp1", ".tmp"),
15
            File.createTempFile("temp2", ".tmp")
16
        )
17
    }
18
    .name { "temp" }
19
    .responseString { request, response, result -> }
Copied!
Specify custom field names for files
1
Fuel.upload("/post")
2
    .dataParts { request, url -> 
3
        listOf( 
4
            //DataPart takes a file, and you can specify the name and/or type
5
            DataPart(File.createTempFile("temp1", ".tmp"), "image/jpeg"), 
6
            DataPart(File.createTempFile("temp2", ".tmp"), "file2"), 
7
            DataPart(File.createTempFile("temp3", ".tmp"), "third-file", "image/jpeg") 
8
        ) 
9
    }
10
    .responseString { request, response, result -> /* ... */ }
Copied!
Upload a multipart form without a file
1
val formData = listOf("Email" to "[email protected]", "Name" to "Joe Smith" )
2
Fuel.upload("/post", param = formData)
3
    // Upload normally requires a file, but we can give it an empty list of `DataPart`
4
    .dataParts { request, url -> listOf<DataPart>() } 
5
    .responseString { request, response, result -> /* ... */ }
Copied!
Upload from an InputStream
1
Fuel.upload("/post")
2
    .blob { request, url -> Blob("filename.png", someObject.length) { someObject.getInputStream() } }
Copied!
Authentication
Support Basic Authentication right off the box
1
  val username = "username"
2
  val password = "abcd1234"
3
​
4
  Fuel.get("https://httpbin.org/basic-auth/$user/$password")
5
      .basicAuthentication(username, password)
6
      .response { request, response, result -> }
Copied!
Support Bearer Authentication
1
  val token = "mytoken"
2
​
3
  Fuel.get("https://httpbin.org/bearer")
4
      .bearerAuthentication(token)
5
      .response { request, response, result -> }
Copied!
Support Any authentication by header
1
  Fuel.get("https://httpbin.org/anything")
2
      .header(Headers.AUTHORIZATION, "Custom secret")
3
      .response { request, response, result -> }
Copied!
Validation
By default, the valid range for HTTP status code will be (200..299).
Cancel
If one wants to cancel on-going request, one could call cancel on the request object
1
  val request = Fuel.get("https://httpbin.org/get")
2
    .response { request, response, result ->
3
      // if request is cancelled successfully, response callback will not be called. 
4
      // Interrupt callback (if provided) will be called instead
5
    }
6
​
7
  //later
8
  request.cancel() //this will cancel on-going request
Copied!
Also, interrupt request can be further processed with interrupt callback
1
  val request = Fuel.get("https://httpbin.org/get")
2
    .interrupt { request -> println("${request.url} was interrupted and cancelled") }
3
    .response { request, response, result ->
4
      // if request is cancelled successfully, response callback will not be called.
5
      // Interrupt callback (if provided) will be called instead
6
    }
7
​
8
  request.cancel()
Copied!
Advanced Configuration
Response Deserialization
Fuel provides built-in support for response deserialization. Here is how one might want to use Fuel together with Gson​
```kotlin //User Model data class User(val firstName: String = "", val lastName: String = "") {
//User Deserializer class Deserializer : ResponseDeserializable { override fun deserialize(content: String) = Gson().fromJson(content, User::class.java) }
}
//Use httpGet extension "https://www.example.com/user/1".httpGet().responseObject(User.Deserializer()) { req, res, result -> //result is of type Result val (user, err) = result
1
println(user.firstName)
2
println(user.lastName)
Copied!
}
1
### Gson Deserialization
2
​
3
* Fuel also provides a built in support for Gson Deserialization. This is possible by including the [Gson](https://github.com/kittinunf/Fuel/tree/master/fuel-gson) module in your dependency block.
4
​
5
```kotlin
6
data class HttpBinUserAgentModel(var userAgent: String = "")
7
Fuel.get("/user-agent")
8
    .responseObject<HttpBinUserAgentModel> { _, _, result -> }
Copied!
Deserialization using kotlinx.serialzationn
requires the kotlinx-serialization extension requires kotlinx.serialization​
1
@Serializable
2
data class HttpBinUserAgentModel(var userAgent: String = "")
3
​
4
Fuel.get("/user-agent")
5
    .responseObject<HttpBinUserAgentModel> { _, _, result -> }
Copied!
This is by default strict and will reject unknown keys, for that you can pass a custom JSOn instance
JSON(nonstrict = true)
1
@Serializable
2
data class HttpBinUserAgentModel(var userAgent: String = "")
3
​
4
Fuel.get("/user-agent")
5
    .responseObject<HttpBinUserAgentModel>(json = JSON(nonstrict = true)) { _, _, result -> }
Copied!
kotlinx.serialization can not always guess the correct serialzer to use, when generics are involved for example
1
@Serializable
2
data class HttpBinUserAgentModel(var userAgent: String = "")
3
​
4
Fuel.get("/list/user-agent")
5
    .responseObject<HttpBinUserAgentModel>(loader = HttpBinUserAgentModel.serilaizer().list) { _, _, result -> }
Copied!
It can be used with coroutines by using kotlinxDeserilaizerOf() it takes the same json and loader as parameters
1
@Serializable
2
data class HttpBinUserAgentModel(var userAgent: String = "")
3
​
4
Fuel.get("/user-agent")
5
    .awaitResponseObject<HttpBinUserAgentModel>(kotlinxDeserializerOf()) { _, _, result -> }
Copied!
There are 4 methods to support response deserialization depending on your needs (also depending on JSON parsing library of your choice), and you are required to implement only one of them.
1
  fun deserialize(bytes: ByteArray): T?
2
​
3
  fun deserialize(inputStream: InputStream): T?
4
​
5
  fun deserialize(reader: Reader): T?
6
​
7
  fun deserialize(content: String): T?
Copied!
Another example may be parsing a website that is not UTF-8. By default, Fuel serializes text as UTF-8, we need to define our deserializer as such
1
  object Windows1255StringDeserializer : ResponseDeserializable<String> {
2
      override fun deserialize(bytes: ByteArray): String {
3
          return String(bytes, "windows-1255")
4
      }
5
  }
Copied!
Configuration
Use singleton FuelManager.instance to manage global configurations.
basePath is used to manage common root path. Great usage is for your static API endpoint.
1
  FuelManager.instance.basePath = "https://httpbin.org"
2
​
3
  // Later
4
  Fuel.get("/get").response { request, response, result ->
5
      //make request to https://httpbin.org/get because Fuel.{get|post|put|delete} use FuelManager.instance to make HTTP request
6
  }
Copied!
baseHeaders is to manage common HTTP header pairs in format of Map<String, String>.
The base headers are only applied if the request does not have those headers set.
1
FuelManager.instance.baseHeaders = mapOf("Device" to "Android")
Copied!
Headers can be added to a request via various methods including
fun header(name: String, value: Any): Request: request.header("foo", "a")
fun header(pairs: Map<String, Any>): Request: request.header(mapOf("foo" to "a"))
fun header(vararg pairs: Pair<String, Any>): Request: request.header("foo" to "a")
operator fun set(header: String, value: Collection<Any>): Request: request["foo"] = listOf("a", "b")
operator fun set(header: String, value: Any): Request: request["foo"] = "a"
By default, all subsequent calls overwrite earlier calls, but you may use the appendHeader variant to append values to existing values.
In earlier versions a mapOf overwrote, and varargs pair did not, but this was confusing.
Some of the HTTP headers are defined under Headers.Companion and can be used instead of literal strings.
1
  Fuel.post("/my-post-path")
2
      .header(Headers.ACCEPT, "text/html, */*; q=0.1")
3
      .header(Headers.CONTENT_TYPE, "image/png")
4
      .header(Headers.COOKIE to "basic=very")
5
      .appendHeader(Headers.COOKIE to "value_1=foo", Headers.COOKIE to "value_2=bar", Headers.ACCEPT to "application/json")
6
      .appendHeader("MyFoo" to "bar", "MyFoo" to "baz")
7
      .response { /*...*/ }
8
​
9
   // => request with:
10
   //    Headers:
11
   //      Accept: "text/html, */*; q=0.1, application/json"
12
   //      Content-Type: "image/png"
13
   //      Cookie: "basic=very; value_1=foo; value_2=bar"
14
   //      MyFoo: "bar, baz"
Copied!
baseParams is used to manage common key=value query param, which will be automatically included in all of your subsequent requests in format of Parameters (Any is converted to String by toString() method)
1
  FuelManager.instance.baseParams = listOf("api_key" to "1234567890")
2
​
3
  // Later
4
  Fuel.get("/get").response { request, response, result ->
5
      //make request to https://httpbin.org/get?api_key=1234567890
6
  }
Copied!
client is a raw HTTP client driver. Generally, it is responsible to make Request into Response. Default is HttpClient which is a thin wrapper over java.net.HttpUrlConnection. You could use any httpClient of your choice by conforming to client protocol, and set back to FuelManager.instance to kick off the effect.
keyStore is configurable by user. By default it is null.
socketFactory can be supplied by user. If keyStore is not null, socketFactory will be derived from it.
hostnameVerifier is configurable by user. By default, it uses HttpsURLConnection.getDefaultHostnameVerifier().
requestInterceptors responseInterceptors is a side-effect to add to Request and/or Response objects.
For example, one might wanna print cUrlString style for every request that hits server in DEBUG mode.
1
  val manager = FuelManager()
2
  if (BUILD_DEBUG) {
3
      manager.addRequestInterceptor(cUrlLoggingRequestInterceptor())
4
  }
5
  val (request, response, result) = manager.request(Method.GET, "https://httpbin.org/get").response() //it will print curl -i -H "Accept-Encoding:compress;q=0.5, gzip;q=1.0" "https://httpbin.org/get"
Copied!
Another example is that you might wanna add data into your Database, you can achieve that with providing responseInterceptors such as
1
  inline fun <reified T> DbResponseInterceptor() =
2
      { next: (Request, Response) -> Response ->
3
          { req: Request, res: Response ->
4
              val db = DB.getInstance()
5
              val instance = Parser.getInstance().parse(res.data, T::class)
6
              db.transaction {
7
                  it.copyToDB(instance)
8
              }
9
              next(req, res)
10
          }
11
      }
12
​
13
  manager.addResponseInterceptor(DBResponseInterceptor<Dog>)
14
  manager.request(Method.GET, "https://www.example.com/api/dog/1").response() // Db interceptor will be called to intercept data and save into Database of your choice
Copied!
Test mode
Testing asynchronized calls can be somehow hard without special care. That's why Fuel has a special test mode with make all the requests blocking, for tests.
1
Fuel.testMode {
2
    timeout = 15000 // Optional feature, set all requests' timeout to this value.
3
}
Copied!
In order to disable test mode, just call Fuel.regularMode()
RxJava Support
Fuel supports RxJava right off the box.
1
  "https://www.example.com/photos/1".httpGet()
2
    .toRxObject(Photo.Deserializer())
3
    .subscribe { /* do something */ }
Copied!
There are 6 extensions over Request that provide RxJava 2.x Single<Result<T, FuelError>> as return type.
1
  fun Request.toRxResponse(): Single<Pair<Response, Result<ByteArray, FuelError>>>
2
  fun Request.toRxResponseString(charset: Charset): Single<Pair<Response, Result<String, FuelError>>>
3
  fun <T : Any> Request.toRxResponseObject(deserializable: Deserializable<T>): Single<Pair<Response, Result<T, FuelError>>>
4
​
5
  fun Request.toRxData(): Single<Result<ByteArray, FuelError>>
6
  fun Request.toRxString(charset: Charset): Single<Result<String, FuelError>>
7
  fun <T : Any> Request.toRxObject(deserializable: Deserializable<T>): Single<Result<T, FuelError>>
Copied!
LiveData Support
Fuel supports LiveData​
1
Fuel.get("www.example.com/get")
2
  .liveDataResponse()
3
  .observe(this) { /* do something */ }
Copied!
Routing Support
In order to organize better your network stack FuelRouting interface allows you to easily setup a Router design pattern.
1
sealed class WeatherApi: FuelRouting {
2
​
3
    override val basePath = "https://www.metaweather.com"
4
​
5
    class weatherFor(val location: String): WeatherApi() {}
6
​
7
    override val method: Method
8
        get() {
9
            when(this) {
10
                is weatherFor -> return Method.GET
11
            }
12
        }
13
​
14
    override val path: String
15
        get() {
16
            return when(this) {
17
                is weatherFor -> "/api/location/search/"
18
            }
19
        }
20
​
21
    override val params: Parameters?
22
        get() {
23
            return when(this) {
24
                is weatherFor -> listOf("query" to this.location)
25
            }
26
        }
27
​
28
    override val headers: Map<String, String>?
29
        get() {
30
            return null
31
        }
32
​
33
}
34
​
35
​
36
// Usage
37
Fuel.request(WeatherApi.weatherFor("london"))
38
    .responseJson { request, response, result ->
39
        result.fold(success = { json ->
40
            Log.d("qdp success", json.array().toString())
41
        }, failure = { error ->
42
            Log.e("qdp error", error.toString())
43
        })
44
    }
Copied!
Coroutines Support
Coroutines module provides extension functions to wrap a response inside a coroutine and handle its result. The coroutines-based API provides equivalent methods to the standard API (e.g: responseString() in coroutines is awaitStringResponse()).
1
runBlocking {
2
    val (request, response, result) = Fuel.get("https://httpbin.org/ip").awaitStringResponse()
3
​
4
    result.fold(
5
        { data -> println(data) /* "{"origin":"127.0.0.1"}" */ }, 
6
        { error -> println("An error of type ${error.exception} happened: ${error.message}") }
7
    )
8
}
Copied!
There are functions to handle Result object directly too.
1
runBlocking {
2
    Fuel.get("https://httpbin.org/ip")
3
        .awaitStringResult()
4
        .fold(
5
            { data -> println(data) /* "{"origin":"127.0.0.1"}" */ }, 
6
            { error -> println("An error of type ${error.exception} happened: ${error.message}") }
7
        )
8
}
Copied!
It also provides useful methods to retrieve the ByteArray,String or Object directly. The difference with these implementations is that they throw exception instead of returning it wrapped a FuelError instance.
1
runBlocking {
2
    try {
3
        println(Fuel.get("https://httpbin.org/ip").awaitString()) // "{"origin":"127.0.0.1"}"
4
    } catch(exception: Exception) {
5
        println("A network request exception was thrown: ${exception.message}")
6
    }
7
}
Copied!
Handling objects other than String (awaitStringResponse()) or ByteArray (awaitByteArrayResponse()) can be done using awaitObject, awaitObjectResult or awaitObjectResponse.
1
data class Ip(val origin: String)
2
​
3
object IpDeserializer : ResponseDeserializable<Ip> {
4
    override fun deserialize(content: String) =
5
        jacksonObjectMapper().readValue<Ip>(content)
6
}
Copied!
1
runBlocking {
2
    Fuel.get("https://httpbin.org/ip")
3
        .awaitObjectResult(IpDeserializer)
4
        .fold(
5
            { data -> println(data.origin) /* 127.0.0.1 */ }, 
6
            { error -> println("An error of type ${error.exception} happened: ${error.message}") }
7
        )
8
}
Copied!
1
runBlocking {
2
    try {
3
        val data = Fuel.get("https://httpbin.org/ip").awaitObject(IpDeserializer)
4
        println(data.origin) // 127.0.0.1
5
    } catch (exception: Exception) {
6
        when (exception){
7
            is HttpException -> println("A network request exception was thrown: ${exception.message}")
8
            is JsonMappingException -> println("A serialization/deserialization exception was thrown: ${exception.message}")
9
            else -> println("An exception [${exception.javaClass.simpleName}\"] was thrown")
10
        }
11
    }
12
}
Copied!
Project Reactor
The Reactor module API provides functions starting with the prefix mono to handle instances of Response, Result<T, FuelError> and values directly (String, ByteArray, Any). All functions expose exceptions as FuelError instance.
Data handling example
1
Fuel.get("https://icanhazdadjoke.com")
2
    .header(Headers.ACCEPT to "text/plain")
3
    .monoString()
4
    .subscribe(::println)
Copied!
Error handling example
1
data class Guest(val name: String)
2
​
3
object GuestMapper : ResponseDeserializable<Guest> {
4
    override fun deserialize(content: String) =
5
        jacksonObjectMapper().readValue<Guest>(content)
6
}
7
​
8
Fuel.get("/guestName").monoResultObject(GuestMapper)
9
    .map(Result<Guest, FuelError>::get)
10
    .map { (name) -> "Welcome to the party, $name!" }
11
    .onErrorReturn("I'm sorry, your name is not on the list.")
12
    .subscribe(::println)
Copied!
Response handling example
1
FuelManager.instance.basePath = "https://httpbin.org"
2
​
3
Fuel.get("/status/404").monoResponse()
4
    .filter(Response::isSuccessful)
5
    .switchIfEmpty(Fuel.get("/status/200").monoResponse())
6
    .map(Response::statusCode)
7
    .subscribe(::println)
Copied!
Other libraries
If you like Fuel, you might also like other libraries of mine;
​Result - The modelling for success/failure of operations in Kotlin
​Fuse - A simple generic LRU memory/disk cache for Android written in Kotlin
​Forge - Functional style JSON parsing written in Kotlin
​ReactiveAndroid - Reactive events and properties with RxJava for Android SDK
Credits
Fuel is brought to you by contributors.
Licenses
Fuel is released under the MIT license.