Fuel
The easiest HTTP networking library for Kotlin/Android.
You are looking at the documentation for 2.x.y.. If you are looking for the documentation for 1.x.y, checkout the 1.16.0 README.md
Features
- HTTP
GET
/POST
/PUT
/DELETE
/HEAD
/PATCH
requests in a fluent style interface - Asynchronous and blocking requests
- Download as a file
- Upload files,
Blob
s,DataPart
s asmultipart/form-data
- Cancel asynchronous request
- Debug logging / convert to cUrl call
- Deserialization into POJO / POKO
- Requests as coroutines
- API Routing
Installation
We offer maven and jitpack installations. Maven via bintray only has stable releases but jitpack can be used to build any branch, commit and version.
Maven
You can download and install Fuel
with Maven
and Gradle
. The core package has the following dependencies:
- Kotlin -
- Result - 3.1.0
//core
implementation 'com.github.kittinunf.fuel:fuel:<latest-version>'
//packages
implementation 'com.github.kittinunf.fuel:<package>:<latest-version>'
Make sure to include mavenCentral()
in your repositories (jcenter()
is deprecated, new releases starting from 2.2.3 are hosted on mavenCentral()
)
repositories {
mavenCentral()
}
Each of the extensions / integrations has to be installed separately.
Package | Description |
---|---|
fuel |
Core package |
fuel-android |
Android: Automatically invoke handler on Main Thread when using Android Module |
fuel-coroutines |
KotlinX: Execution with coroutines |
fuel-forge |
Deserialization: Forge |
fuel-gson |
(De)serialization: Gson |
fuel-jackson |
Deserialization: Jackson |
fuel-json |
Deserialization: Json |
fuel-kotlinx-serialization |
(De)serialization: KotlinX Serialization |
fuel-livedata |
Android Architectures: Responses as LiveData |
fuel-moshi |
Deserialization: Moshi |
fuel-reactor |
Reactive Programming: Responses as Mono (Project Reactor 3.x) |
fuel-rxjava |
Reactive Programming: Responses as Single (RxJava 2.x) |
fuel-stetho |
Utility: Debug utility for Android on Chrome Developer Tools, Stetho |
Jitpack
If you want a SNAPSHOT distribution, you can use Jitpack
repositories {
maven(url = "https://www.jitpack.io") {
name = "jitpack"
}
}
dependencies {
//core
implementation(group = "com.github.kittinunf.fuel", name = "fuel", version = "-SNAPSHOT")
//packages
// replace <package> with the package name e.g. fuel-coroutines
implementation(group = "com.github.kittinunf.fuel", name = "<package>", version = "-SNAPSHOT")
}
or
dependencies {
//core and/or packages
// replace <package> with the package name e.g. fuel-coroutines
listof("fuel", "<package>").forEach {
implementation(group = "com.github.kittinunf.fuel", name = it, version = "-SNAPSHOT")
}
}
Configuration
-
group
is made up ofcom.github
as well as username and project name -
name
is the subproject, this may be any of the packages listed in the installation instructions eg.fuel
,fuel-coroutines
,fuel-kotlinx-serialization
, etc -
version
can be the latestmaster-SMAPSHOT
or-SNAPSHOT
which always points at the HEAD or any other branch, tag or commit hash, e.g. as listed on jitpack.io.
We recommend not using SNAPSHOT
builds, but a specific commit in a specific branch (like a commit on master), because your build will then be stable.
Build time-out
Have patience when updating the version of fuel or building for the first time as jitpack will build it, and this may cause the request to jitpack to time out. Wait a few minutes and try again (or check the status on jitpack).
NOTE: do not forget to add the kotlinx
repository when using coroutines
or serialization
Forks
Jitpack.io also allows to build from fuel
forks. If a fork's username is $yourname
,
- adjust
group
tocom.github.$yourName.fuel
- and look for
version
onhttps://jitpack.io/#$yourName/Fuel
Quick start
Fuel requests can be made on the Fuel
namespace object, any FuelManager
or using one of the String
extension methods. If you specify a callback the call is async
, if you don't it's blocking
.
Async Usage Example
import com.github.kittinunf.fuel.httpGet
import com.github.kittinunf.result.Result
fun main(args: Array<String>) {
val httpAsync = "https://httpbin.org/get"
.httpGet()
.responseString { request, response, result ->
when (result) {
is Result.Failure -> {
val ex = result.getException()
println(ex)
}
is Result.Success -> {
val data = result.get()
println(data)
}
}
}
httpAsync.join()
}
Blocking Usage Example
import com.github.kittinunf.fuel.httpGet
import com.github.kittinunf.result.Result;
fun main(args: Array<String>) {
val (request, response, result) = "https://httpbin.org/get"
.httpGet()
.responseString()
when (result) {
is Result.Failure -> {
val ex = result.getException()
println(ex)
}
is Result.Success -> {
val data = result.get()
println(data)
}
}
}
// You can also use Fuel.get("https://httpbin.org/get").responseString { ... }
// You can also use FuelManager.instance.get("...").responseString { ... }
Fuel
and the extension methods use the FuelManager.instance
under the hood. You can use this FuelManager to change the default behaviour of all requests:
FuelManager.instance.basePath = "https://httpbin.org"
"/get"
.httpGet()
.responseString { request, response, result -> /*...*/ }
// This is a GET request to "https://httpbin.org/get"
Detailed usage
Check each of the packages documentations or the Wiki for more features, usages and examples. Are you looking for basic usage on how to set headers, authentication, request bodies and more? fuel
: Basic usage is all you need.
Basic functionality
Responses
fuel-livedata
: Responses as LiveDatafuel-reactor
: Responses as Monofuel-rxjava
: Responses as Single
(De)serialization
fuel-forge
: Deserialization with Forgefuel-gson
: (De)serialization with Gsonfuel-jackson
: Deserialization with Jacksonfuel-json
: Deserialization with Jsonfuel-kotlinx-serialization
: (De)serialization with KotlinX Serializationfuel-moshi
: Deserialization with Moshi
Utility
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.