The easiest HTTP networking library for Kotlin/Android
Clone or download
markGilchrist and iNoles Add suspending implenetation client (#438)
* initial commit

* 3 out of 17 test pass, may be making progress here

* more changes

* more changes

* implement kitteuns comment

* tidied up imports

* tidied up imports

* small changes

* All tests passing, all credit to jonathan/inoles

* All tests passing, all credit to jonathan/inoles for comment

* code formatting and remove unwanted imports

* resolved conflicts all test passing

* respond to police icon

* moving over to kotlin 1.3 still not working

* remove police warning

* running kotlin 1.3 all tests passing

* minor changes

* updated samples as per iNoles eagle eye suggestion

* minor update to remove redundant let

* updated following comments

* added default implemenation to client

* updated still no building

* again sleepless byte saves the day by showing me where I went wrong

* responsed to comments ATP

* inoles saves the day
Latest commit ad3e014 Oct 16, 2018
Permalink
Failed to load latest commit information.
.github πŸ“ Fix minor details on PR template (#460) Oct 14, 2018
buildSrc Add suspending implenetation client (#438) Oct 16, 2018
fuel-android Mock all the projects (#444) Sep 28, 2018
fuel-coroutines Add suspending implenetation client (#438) Oct 16, 2018
fuel-forge Fixed and Improve Coverage of Forge. (#443) Sep 30, 2018
fuel-gson Mock all the projects (#444) Sep 28, 2018
fuel-jackson Mock all the projects (#444) Sep 28, 2018
fuel-kotlinx-serialization Add suspending implenetation client (#438) Oct 16, 2018
fuel-livedata Mock all the projects (#444) Sep 28, 2018
fuel-moshi Allow custom adapters in moshiDeserializerOf() for Moshi (#441) Oct 7, 2018
fuel-reactor Integration with Project Reactor (#424) Oct 5, 2018
fuel-rxjava Improve RxJava Coverages (#445) Sep 30, 2018
fuel Add suspending implenetation client (#438) Oct 16, 2018
gradle/wrapper Add suspending implenetation client (#438) Oct 16, 2018
sample-java πŸ’„ πŸ›  Migrate Gradle scripts to Kotlin DSL (#423) Sep 15, 2018
sample Add suspending implenetation client (#438) Oct 16, 2018
.gitignore Testing: mock all the things (#434) Sep 22, 2018
.travis.yml Revert "Added Travis Retry on Gradlew (#455)" (#456) Oct 11, 2018
CHANGELOG.md Merge branch 'feature/community-and-contributing' of https://github.c… Sep 11, 2018
CODE_OF_CONDUCT.md Add a code of conduct Sep 11, 2018
CONTRIBUTING.md Fix a typo in CONTRIBUTING.md (#452) Oct 5, 2018
LICENSE.md πŸ“ Update license year (#428) Sep 11, 2018
README.md add kotlinxSerialization JSON deseriallization (#450) Oct 9, 2018
build.gradle.kts Add suspending implenetation client (#438) Oct 16, 2018
deploy_bintray.sh Fix publishing script (#459) Oct 13, 2018
gradlew ⬆️ Updates gradle and bintray versions (#239) Sep 22, 2017
gradlew.bat Update dependencies ⬆️ Jan 9, 2017
settings.gradle.kts Add suspending implenetation client (#438) Oct 16, 2018

README.md

Fuel

Kotlin jcenter Build Status Codecov

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 (Gson, Jackson, Moshi, Forge) ✨
  • Support Kotlin's Coroutines module
  • API Routing

Installation

Dependency - fuel

  • Result - The modelling for success/failure of operations in Kotlin

Dependency - fuel-android

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

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

repositories {
    jcenter()
}

dependencies {
    compile 'com.github.kittinunf.fuel:fuel:<latest-version>' //for JVM
    compile 'com.github.kittinunf.fuel:fuel-android:<latest-version>' //for Android
    compile 'com.github.kittinunf.fuel:fuel-livedata:<latest-version>' //for LiveData support
    compile 'com.github.kittinunf.fuel:fuel-rxjava:<latest-version>' //for RxJava support
    compile 'com.github.kittinunf.fuel:fuel-coroutines:<latest-version>' //for Kotlin Coroutines support
    compile 'com.github.kittinunf.fuel:fuel-gson:<latest-version>' //for Gson support
    compile 'com.github.kittinunf.fuel:fuel-jackson:<latest-version>' //for Jackson support
    compile 'com.github.kittinunf.fuel:fuel-moshi:<latest-version>' //for Moshi support
    compile 'com.github.kittinunf.fuel:fuel-forge:<latest-version>' //for Forge support
    compile 'com.github.kittinunf.fuel:fuel-reactor:<latest-version>' //for Reactor support
}

Sample

  • There are two samples, one is in Kotlin and another one in Java.

Quick Glance Usage

Async mode

  • 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 -> {
      val ex = result.getException()
    }
    is Result.Success -> {
      val data = result.get()
    }
  }
}

//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
	})
}
  • Java
//get
Fuel.get("https://httpbin.org/get", params).responseString(new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
    	//do something when it is failure
    }

    @Override
    public void success(Request request, Response response, String data) {
    	//do something when it is successful
    }
});

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
val (request, response, result) = "https://httpbin.org/get".httpGet().responseString() // result is Result<String, FuelError>
  • Java
try {
    Triple<Request, Response, String> data = Fuel.get("https://www.google.com").responseString();
    Request request = data.getFirst();
    Response response = data.getSecond();
    Result<String,FuelError> text = data.getThird();
} catch (Exception networkError) {

}

Detail Usage

GET

Fuel.get("https://httpbin.org/get").response { request, response, result ->
    println(request)
    println(response)
    val (bytes, error) = result
    if (bytes != null) {
        println(bytes)
    }
}

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

fun response(handler: (Request, Response, Result<ByteArray, FuelError>) -> Unit)

Response in String

fun responseString(handler: (Request, Response, Result<String, FuelError>) -> Unit)

Response in Json

requires the android extension

fun responseJson(handler: (Request, Response, Result<Json, FuelError>) -> Unit)

val jsonObject = json.obj() //JSONObject
val jsonArray = json.array() //JSONArray

Response in T (object)

fun <T> responseObject(deserializer: ResponseDeserializable<T>, handler: (Request, Response, Result<T, FuelError>) -> Unit)

POST

Fuel.post("https://httpbin.org/post").response { request, response, result ->
}

//if you have body to post it manually
Fuel.post("https://httpbin.org/post").jsonBody("{ \"foo\" : \"bar\" }").response { request, response, result ->
}

PUT

Fuel.put("https://httpbin.org/put").response { request, response, result ->
}

DELETE

Fuel.delete("https://httpbin.org/delete").response { request, response, result ->
}

HEAD

Fuel.head("https://httpbin.org/get").response { request, response, result ->
   // request body should be empty.
}

PATCH

Fuel.patch("https://httpbin.org/patch").response { request, response, result ->
   // request body should be empty.
}

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:

Fuel.request(Method.OPTIONS, "https://httpbin.org/anything").response { request, response, result ->
}

TRACE

There are no convenience methods for making an TRACE request, but you can still make one directly:

Fuel.request(Method.TRACE, "https://httpbin.org/anything").response { request, response, result ->
}

Debug Logging

  • Use toString() method to Log (request|response)
Log.d("log", request.toString())
//print and header detail
//request
--> GET (https://httpbin.org/get?key=value)
    Body : (empty)
    Headers : (2)
    Accept-Encoding : compress;q=0.5, gzip;q=1.0
    Device : Android

//response
<-- 200 (https://httpbin.org/get?key=value)
  • Also support cUrl string to Log request, make it very easy to cUrl on command line
Log.d("cUrl log", request.cUrlString())
//print
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"

Parameter Support

  • URL encoded style for GET & DELETE request
Fuel.get("https://httpbin.org/get", listOf("foo" to "foo", "bar" to "bar")).response { request, response, result -> {
    //resolve to https://httpbin.org/get?foo=foo&bar=bar
}

Fuel.delete("https://httpbin.org/delete", listOf("foo" to "foo", "bar" to "bar")).response { request, response, result ->
    //resolve to https://httpbin.org/delete?foo=foo&bar=bar
}
  • Array support for GET requests
Fuel.get("https://httpbin.org/get", listOf("foo" to "foo", "dwarf" to  arrayOf("grumpy","happy","sleepy","dopey"))).response { request, response, result -> {
    //resolve to https://httpbin.org/get?foo=foo&dwarf[]=grumpy&dwarf[]=happy&dwarf[]=sleepy&dwarf[]=dopey
}
  • Support x-www-form-urlencoded for PUT & POST
Fuel.post("https://httpbin.org/post", listOf("foo" to "foo", "bar" to "bar")).response { request, response, result ->
    //http body includes foo=foo&bar=bar
}

Fuel.put("https://httpbin.org/put", listOf("foo" to "foo", "bar" to "bar")).response { request, response, result ->
    //http body includes foo=foo&bar=bar
}

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
val timeout = 5000 // 5000 milliseconds = 5 seconds.
val timeoutRead = 60000 // 60000 milliseconds = 1 minute.

"https://httpbin.org/get".httpGet().timeout(timeout).timeoutRead(timeoutRead).responseString { request, response, result -> }
  • Java
int timeout = 5000 // 5000 milliseconds = 5 seconds.
int timeoutRead = 60000 // 60000 milliseconds = 1 minute.
Fuel.get("https://httpbin.org/get", params).timeout(timeout).timeoutRead(timeoutRead).responseString(new Handler<String>() {
    @Override
    public void failure(Request request, Response response, FuelError error) {
    	//do something when it is failure
    }

    @Override
    public void success(Request request, Response response, String data) {
    	//do something when it is successful
    }
});

Download with or without progress handler

Fuel.download("https://httpbin.org/bytes/32768").destination { response, url ->
    File.createTempFile("temp", ".tmp")
}.response { req, res, result ->

}

Fuel.download("https://httpbin.org/bytes/32768").destination { response, url ->
    File.createTempFile("temp", ".tmp")
}.progress { readBytes, totalBytes ->
    val progress = readBytes.toFloat() / totalBytes.toFloat()
}.response { req, res, result ->

}

Upload with or without progress handler

Fuel.upload("/post").source { request, url ->
    File.createTempFile("temp", ".tmp");
}.responseString { request, response, result ->

}

//by default upload use Method.POST, unless it is specified as something else
Fuel.upload("/put", Method.PUT).source { request, url ->
    File.createTempFile("temp", ".tmp");
}.responseString { request, response, result ->
    // calls to https://example.com/api/put with PUT

}

//upload with multiple files
Fuel.upload("/post").sources { request, url ->
    listOf(
        File.createTempFile("temp1", ".tmp"),
        File.createTempFile("temp2", ".tmp")
    )
}.name {
    "temp"
}.responseString { request, response, result ->

}

Specify custom field names for files

Fuel.upload("/post").dataParts { request, url -> 
    listOf( 
        //DataPart takes a file, and you can specify the name and/or type
	DataPart(File.createTempFile("temp1", ".tmp"), "image/jpeg"), 
	DataPart(File.createTempFile("temp2", ".tmp"), "file2"), 
	DataPart(File.createTempFile("temp3", ".tmp"), "third-file", "image/jpeg") 
    ) 
}.responseString { request, response, result ->
    ... 
}

Upload a multipart form without a file

val formData = listOf("Email" to "mail@example.com", "Name" to "Joe Smith" )
Fuel.upload("/post", param = formData)
    //Upload normally requires a file, but we can give it an empty list of `DataPart`
    .dataParts { request, url -> listOf<DataPart>() } 
    .responseString { request, response, result ->
        ...
    }

Upload from an InputStream

Fuel.upload("/post").blob { request, url ->
    Blob("filename.png", someObject.length, { someObject.getInputStream() })
}

Authentication

  • Support Basic Authentication right off the box
val username = "username"
val password = "abcd1234"

Fuel.get("https://httpbin.org/basic-auth/$user/$password").authenticate(username, password).response { request, response, result ->
}

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
val request = Fuel.get("https://httpbin.org/get").response { request, response, result ->
    // if request is cancelled successfully, response callback will not be called. Interrupt callback (if provided) will be called instead
}

//later
request.cancel() //this will cancel on-going request
  • Also, interrupt request can be further processed with interrupt callback
val request = Fuel.get("https://httpbin.org/get").interrupt { request ->
    println("${request.url} was interrupted and cancelled")
}.response { request, response, result ->
    // if request is cancelled successfully, response callback will not be called. Interrupt callback (if provided) will be called instead
}

request.cancel()

Advanced Configuration

Response Deserialization

  • Fuel provides built-in support for response deserialization. Here is how one might want to use Fuel together with Gson
//User Model
data class User(val firstName: String = "",
                val lastName: String = "") {

    //User Deserializer
    class Deserializer : ResponseDeserializable<User> {
        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<User, Exception>
    val (user, err) = result

    println(user.firstName)
    println(user.lastName)
}

Gson Deserialization

  • Fuel also provides a built in support for Gson Deserialization. This is possible by including the Gson module in your dependency block.
data class HttpBinUserAgentModel(var userAgent: String = "")

Fuel.get("/user-agent").responseObject<HttpBinUserAgentModel> { _, _, result ->
}

Deserialization using kotlinx.serialzationn

requires the kotlinx-serialization extension requires kotlinx.serialization

@Serializable
data class HttpBinUserAgentModel(var userAgent: String = "")

Fuel.get("/user-agent").responseObject<HttpBinUserAgentModel> { _, _, result ->
}

this is by default strict and will reject unknown keys, for that you can pass a custom JSOn instance

JSON(nonstrict = true)

@Serializable
data class HttpBinUserAgentModel(var userAgent: String = "")

Fuel.get("/user-agent").responseObject<HttpBinUserAgentModel>(json = JSON(nonstrict = true)) { _, _, result ->
}

kotlinx.serialization can not always guess the correct serialzer to use, when generics are involved for example

@Serializable
data class HttpBinUserAgentModel(var userAgent: String = "")

Fuel.get("/list/user-agent").responseObject<HttpBinUserAgentModel>(loader = HttpBinUserAgentModel.serilaizer().list) { _, _, result ->
}

it can be used with coroutines by using kotlinxDeserilaizerOf() it takes the same json and loader as parameters

@Serializable
data class HttpBinUserAgentModel(var userAgent: String = "")

Fuel.get("/user-agent").awaitResponseObject<HttpBinUserAgentModel>(kotlinxDeserializerOf()) { _, _, result ->
}
  • 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.
public fun deserialize(bytes: ByteArray): T?

public fun deserialize(inputStream: InputStream): T?

public fun deserialize(reader: Reader): T?

public fun deserialize(content: String): T?
  • 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
object Windows1255StringDeserializer : ResponseDeserializable<String> {
        override fun deserialize(bytes: ByteArray): String {
            return String(bytes, "windows-1255")
        }
    }

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.

FuelManager.instance.basePath = "https://httpbin.org"
Fuel.get("/get").response { request, response, result ->
    //make request to https://httpbin.org/get because Fuel.{get|post|put|delete} use FuelManager.instance to make HTTP request
}
  • baseHeaders is to manage common HTTP header pairs in format of Map<String, String>>.
FuelManager.instance.baseHeaders = mapOf("Device" to "Android")
  • Headers can be add to a request via the methods fun header(pairs: Map<String, Any>?): Request or fun header(vararg pairs: Pair<String, Any>?).

  • The latter method does support multiple values for the same key however as fun header(pairs: Map<String, Any>?): Request takes a map this method can not support multiple values for the same key as per the definition of the map.

Fuel.get("/get").response { request, response, result ->
    //make request to https://httpbin.org/get with global device header (Device : Android)
}
  • baseParams is used to manage common key=value query param, which will be automatically included in all of your subsequent requests in format of List<Pair<String, Any?>> (Any is converted to String by toString() method)
FuelManager.instance.baseParams = listOf("api_key" to "1234567890")
Fuel.get("/get").response { request, response, result ->
    //make request to https://httpbin.org/get?api_key=1234567890
}
  • 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.HttpUrlConnnection. 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.

val manager = FuelManager()
if (BUILD_DEBUG) {
    manager.addRequestInterceptor(cUrlLoggingRequestInterceptor())
}
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"
  • Another example is that you might wanna add data into your Database, you can achieve that with providing responseInterceptors such as
inline fun <reified T> DbResponseInterceptor() =
        { next: (Request, Response) -> Response ->
            { req: Request, res: Response ->
                val db = DB.getInstance()
                val instance = Parser.getInstance().parse(res.data, T::class)
                db.transaction {
                    it.copyToDB(instance)
                }
                next(req, res)
            }
        }

manager.addResponseInterceptor(DBResponseInterceptor<Dog>)
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

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.

Fuel.testMode {
    timeout = 15000 // Optional feature, set all requests' timeout to this value.
}

In order to disable test mode, just call Fuel.regularMode()

RxJava Support

  • Fuel supports RxJava right off the box.
"https://www.example.com/photos/1".httpGet().rx_object(Photo.Deserializer()).subscribe {
	//do something
}
  • There are 6 extensions over Request that provide RxJava 2.x Single<Result<T, FuelError>> as return type.
fun Request.rx_response(): Single<Pair<Response, Result<ByteArray, FuelError>>>
fun Request.rx_responseString(charset: Charset): Single<Pair<Response, Result<String, FuelError>>>
fun <T : Any> Request.rx_responseObject(deserializable: Deserializable<T>): Single<Pair<Response, Result<T, FuelError>>>

fun Request.rx_data(): Single<Result<ByteArray, FuelError>>
fun Request.rx_string(charset: Charset): Single<Result<String, FuelError>>
fun <T : Any> Request.rx_object(deserializable: Deserializable<T>): Single<Result<T, FuelError>>

LiveData Support

Fuel.get("www.example.com/get").liveDataResponse().observe(this) {
  //do something
}

Routing Support

In order to organize better your network stack FuelRouting interface allows you to easily setup a Router design pattern.

sealed class WeatherApi: FuelRouting {

    override val basePath = "https://www.metaweather.com"

    class weatherFor(val location: String): WeatherApi() {}

    override val method: Method
        get() {
            when(this) {
                is weatherFor -> return Method.GET
            }
        }

    override val path: String
        get() {
            return when(this) {
                is weatherFor -> "/api/location/search/"
            }
        }

    override val params: List<Pair<String, Any?>>?
        get() {
            return when(this) {
                is weatherFor -> listOf("query" to this.location)
            }
        }

    override val headers: Map<String, String>?
        get() {
            return null
        }

}


// Usage
Fuel.request(WeatherApi.weatherFor("london")).responseJson { request, response, result ->
            result.fold(success = { json ->
                Log.d("qdp success", json.array().toString())
            }, failure = { error ->
                Log.e("qdp error", error.toString())
            })
        }

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()).

runBlocking {
    val (request, response, result) = Fuel.get("https://httpbin.org/ip").awaitStringResponse()

    result.fold({ data ->
        println(data) // "{"origin":"127.0.0.1"}"
    }, { error ->
        println("An error of type ${error.exception} happened: ${error.message}")
    })
}

There are functions to handle Result object directly too.

runBlocking {
    Fuel.get("https://httpbin.org/ip").awaitStringResult()
        .fold({ data ->
            println(data) // "{"origin":"127.0.0.1"}"
        }, { error ->
            println("An error of type ${error.exception} happened: ${error.message}")
        })
}

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.

runBlocking {
    try {
        println(Fuel.get("https://httpbin.org/ip").awaitString()) // "{"origin":"127.0.0.1"}"
    } catch(exception: Exception) {
        println("A network request exception was thrown: ${exception.message}")
    }
}

Handling objects other than String (awaitStringResponse()) or ByteArray (awaitByteArrayResponse()) can be done using awaitObject, awaitObjectResult or awaitObjectResponse.

data class Ip(val origin: String)

object IpDeserializer : ResponseDeserializable<Ip> {
    override fun deserialize(content: String) =
        jacksonObjectMapper().readValue<Ip>(content)
}
runBlocking {
    Fuel.get("https://httpbin.org/ip").awaitObjectResult(IpDeserializer)
        .fold({ data ->
            println(data.origin) // 127.0.0.1
        }, { error ->
            println("An error of type ${error.exception} happened: ${error.message}")
        })
}
runBlocking {
    try {
        val data = Fuel.get("https://httpbin.org/ip").awaitObject(IpDeserializer)
        println(data.origin) // 127.0.0.1
    } catch (exception: Exception) {
        when (exception){
            is HttpException -> println("A network request exception was thrown: ${exception.message}")
            is JsonMappingException -> println("A serialization/deserialization exception was thrown: ${exception.message}")
            else -> println("An exception [${exception.javaClass.simpleName}\"] was thrown")
        }
    }
}

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

Fuel.get("https://icanhazdadjoke.com")
    .header("Accept" to "text/plain")
    .monoString()
    .subscribe(::println)

Error handling example

data class Guest(val name: String)

object GuestMapper : ResponseDeserializable<Guest> {
    override fun deserialize(content: String) =
        jacksonObjectMapper().readValue<Guest>(content)
}

Fuel.get("/guestName").monoResultObject(GuestMapper)
    .map(Result<Guest, FuelError>::get)
    .map { (name) -> "Welcome to the party, $name!" }
    .onErrorReturn("I'm sorry, your name is not on the list.")
    .subscribe(::println)

Response handling example

FuelManager.instance.basePath = "https://httpbin.org"

Fuel.get("/status/404").monoResponse()
    .filter(Response::isSuccessful)
    .switchIfEmpty(Fuel.get("/status/200").monoResponse())
    .map(Response::statusCode)
    .subscribe(::println)

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.