Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

Fuel

The easiest HTTP networking library for Kotlin/Android

Subscribe to updates I use Fuel


Statistics on Fuel

Number of watchers on Github 1553
Number of open issues 45
Average time to close an issue 8 days
Main language Kotlin
Average time to merge a PR 4 days
Open pull requests 16+
Closed pull requests 12+
Last commit over 1 year ago
Repo Created about 4 years ago
Repo Last Updated over 1 year ago
Size 926 KB
Organization / Authorkittinunf
Latest Release1.12.1
Contributors4
Page Updated
Do you use Fuel? Leave a review!
View open issues (45)
View Fuel activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating Fuel for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Fuel

Kotlin jcenter Build Status Codecov

The easiest HTTP networking library for Kotlin/Android.

Features

  • [x] Support basic HTTP GET/POST/PUT/DELETE/HEAD/PATCH in a fluent style interface
  • [x] Support both asynchronous and blocking requests
  • [x] Download file
  • [x] Upload file (multipart/form-data)
  • [x] Cancel in-flight request
  • [x] Request timeout
  • [x] Configuration manager by using FuelManager
  • [x] Debug log / cUrl log
  • [x] Support response deserialization into plain old object (both Kotlin & Java)
  • [x] Automatically invoke handler on Android Main Thread when using Android Module
  • [x] Special test mode for easier testing
  • [x] RxJava 2.x support out of the box
  • [x] Google Components LiveData support
  • [x] Gson module support
  • [x] 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-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

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-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
}

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()) http://httpbin.org/get.httpGet().responseString { request, response, result -> //do something with response when (result) { is Result.Failure -> { error = result.getAs() } is Result.Success -> { data = result.getAs() } } }

//if we set baseURL beforehand, simply use relativePath FuelManager.instance.basePath = http://httpbin.org /get.httpGet().responseString { request, response, result -> //make a GET to http://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(http://httpbin.org/get).responseString { request, response, result -> //do something with response result.fold({ d -> //do something with data }, { err -> //do something with error }) }


* Java
``` Java
//get
Fuel.get("http://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) = "http://httpbin.org/get".httpGet().responseString() // result is Result<String, FuelError>
    
  • Java

    try {
    Triple<Request, Response, String> data = Fuel.get("http://www.google.com").responseString();
    Request request = data.getFirst();
    Response response = data.getSecond();
    Result<String,FuelError> text = data.getThird();
    } catch (Exception networkError) {
    

}


## Detail Usage

### GET

``` Kotlin
Fuel.get("http://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 extention

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("http://httpbin.org/post").response { request, response, result ->
}

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

PUT

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

DELETE

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

HEAD

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

PATCH

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

Debug Logging

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

//response
<-- 200 (http://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" "http://httpbin.org/post"

Parameter Support

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

Fuel.delete("http://httpbin.org/delete", listOf("foo" to "foo", "bar" to "bar")).response { request, response, result ->
    //resolve to http://httpbin.org/get?foo=foo&bar=bar
}
  • Support x-www-form-urlencoded for PUT & POST
Fuel.post("http://httpbin.org/post", listOf("foo" to "foo", "bar" to "bar")).response { request, response, result ->
    //http body includes foo=foo&bar=bar
}

Fuel.put("http://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 ```kotlin val timeout = 5000 // 5000 milliseconds = 5 seconds. val readTimeout = 60000 // 60000 milliseconds = 1 minute.

http://httpbin.org/get.httpGet().timeout(timeout).readTimeout(readTimeout).responseString { request, response, result -> }


* Java
``` Java
int timeout = 5000 // 5000 milliseconds = 5 seconds.
int readTimeout = 60000 // 60000 milliseconds = 1 minute.
Fuel.get("http://httpbin.org/get", params).timeout(timeout).readTimeout(readTimeout).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("http://httpbin.org/bytes/32768").destination { response, url ->
    File.createTempFile("temp", ".tmp")
}.response { req, res, result ->

}

Fuel.download("http://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 http://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 ``` Kotlin val username = username val password = abcd1234

Fuel.get(http://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
``` Kotlin
val request = Fuel.get("http://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 ``` Kotlin val request = Fuel.get(http://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](https://github.com/google/gson)

``` Kotlin

//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
"http://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 ->
}
  • 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")
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, "http://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.
"http://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())
            })
        }

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.

Fuel open issues Ask a question     (View All Issues)
  • almost 3 years (Java) Passing body / header in an upload task
  • almost 3 years help for keeping session open
  • almost 3 years JRE 7 required to use Basic Authentication
  • almost 3 years Field name for uploaded file
  • almost 3 years Boundary should keep same in one upload request
  • almost 3 years Useless try-catch block
  • about 3 years httpGet() and httpPost() differ in request encoding?
  • about 3 years Possibility to invoke handler in background thread on Android
  • about 3 years Out of memory when downloading file.
  • about 3 years TLS 1.2 support
  • about 3 years Progress not updating
  • about 3 years Way to retrieve redirection info
  • about 3 years Malformed header cause failure
  • about 3 years Hangs on at exit
  • about 3 years Allow setting timeout on FuelManager
  • over 3 years `cancel()` doesn't cancel the underlying HTTP request.
  • over 3 years Can upload a file with params ?
Fuel open pull requests (View All Pulls)
  • Fix incorrect example in README.md
  • master
  • fix upload task
  • Possible IllegalStateException
  • Add PATCH method for Fuel
  • Added ability to send/receive big files by using real stream instead of bytestream.
  • Add response.guessContentType() and improve .toString()
  • Also check for lowercase `location` header on redirect
  • 1、[Add]:Add fastjson;
  • Support Forge
  • Gradle updates
  • Add HTTP status code 303 as valid redirect
  • #246, #168: Add Kotlin Coroutines support
  • Add ability to set timeout in FuelManager to resolve #94
  • Fix Error in README.md
  • FuelRouting / Add support for Json request
Fuel questions on Stackoverflow (View All Questions)
  • Fuel CMS vs ionizecms
  • A Shortest path with fuel constraints
  • Fuel Gauge android UI control example
  • MySql Finding Reading and Fuel Consumption Average of Vehicle
  • fuel ux wizard cache
  • Installing Fuel (Machine Learning) using pip on Ubuntu 14.04.02
  • Fuel consumption from OBD2 port parameters
  • How does Fuel CMS update the database through Simple Modules?
  • How to upgrade docker in fuel master?
  • Bootstrap datepicker and Fuel UX datepicker conflicting
  • Mirantis Fuel 6.1 : Deployment using scripts
  • Fuel UX 3: is element id required for initialization through Javascript?
  • fuel cms of codeigniter not working
  • How to create custom Icons in Ionic framework for fuel stations and food courts
  • How to preselect items within a Fuel UX treeview?
  • fuel setup on mac / h5py setup on mac - hdf5.h file not found
  • Fuel UX - Hook onto change event of wizard
  • Expand All Folders using fuel ux treeview
  • How to calculate all MPG in a list of Fuel Entries from Realm Database
  • Fuel UX wizard is not working
  • jQuery UI and Fuel UX conflict
  • accessing 'blog' functionality / template in FUEL CMS
  • allow custom modules in fuel CMS
  • Fuel add new compute-code, but time is not sync, and instance cannot start, error: β€˜vif_type=binding_failed’
  • How to create 'blog' and new page in Fuel CMS with CI
  • can't clone sql object in fuel php
  • How to reload data in a Fuel UX repeater
  • redirect to a subpage as the homepage in a fuel CMS website
  • Fuel and MongoDB
  • Fuel gauge to measure usb OTG consumption
Fuel list of languages used
Fuel latest release notes
1.12.1 Fuel - 1.12.1

Release v1.12.1

  • [x] Add test for responseInterceptor by @kindraywind
  • [x] Fix cUrlString() format by @babedev
  • [x] Fix synchronous call with moshi responseObject() to return T instead of Any by @rwhite226
  • [x] Mark created threads as daemon thread so they can't hang the program by @nanodeath
  • [x] Responses not validated after redirect by @anatolykislov
  • [x] Updated README to indicate responseJson dependency by @Guppster
  • [x] Corrected example in readme.md by @Guppster
  • [x] Add tests for Moshi module
  • [x] Update dependencies versions
  • [x] Fix upload boundary by @babedev
  • [x] Add response.guessContentType() and improve .toString() by @kindraywind
  • [x] Add Base64 tests by @kindraywind

Thanks everyone for contributing. I wish I could buy you all .

ttt1.12.0 Fuel - 1.12.0

Release v1.12

  • [x] DownloadTaskRequest: Properly close the FileOutputStream #255
  • [x] Support Moshi deserialization #260
  • [x] Pass the expected object type through #261
  • [x] Fix type issue with usage with Jackson in sync mode #268

Huge thanks to everyone who help contribute to Fuel, much appreciated

1.11.0 Fuel - 1.11.0

Release v1.11

  • [x] Fix json typing by @yoavst
  • [x] :sparkles: Add Jackson deserialization support by @deiga
  • [x] :arrow_up: Updates gradle and bintray versions by @deiga
  • [x] :rotating_light: Fixes deprecation warnings by @deiga
  • [x] UrlEncode POST parameters by @mbreithu

Huge thanks to everyone who help contribute to Fuel, much appreciated

Other projects in Kotlin