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, Blobs, DataParts as multipart/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 - 1.3.20
Coroutine - 1.1.1

compile 'com.github.kittinunf.fuel:<package>:<latest-version>'

Each of the extensions / integrations has to be installed separately.

Package	Description
`fuel`	Core package
`fuel-coroutines`	KotlinX: Execution with coroutines
`fuel-android`	Android: Automatically invoke handler on Main Thread when using Android Module
`fuel-livedata`	Android Architectures: Responses as `LiveData`
`fuel-rxjava`	Reactive Programming: Responses as `Single` (RxJava 2.x)
`fuel-reactor`	Reactive Programming: Responses as `Mono` (Project Reactor 3.x)
`fuel-gson`	(De)serialization: `Gson`
`fuel-kotlinx-serialization`	(De)serialization: `KotlinX Serialization`
`fuel-json`	Deserialization: `Json`
`fuel-forge`	Deserialization: `Forge`
`fuel-jackson`	Deserialization: `Jackson`
`fuel-moshi`	Deserialization: `Moshi`

Jitpack

repositories {
  maven(url = "https://jitpack.io") {
    name = "jitpack"
  }
}

dependencies {
  implementation(group = "com.github.kittinunf.fuel", name = "fuel", version = "-SNAPSHOT")
  implementation(group = "com.github.kittinunf.fuel", name = "fuel-coroutines", version = "-SNAPSHOT")
  implementation(group = "com.github.kittinunf.fuel", name = "fuel-kotlinx-serialization", version = "-SNAPSHOT")
}

dependencies {
  listof("fuel", "fuel-coroutines", "fuel-kotlinx-serialization").forEach {
    implementation(group = "com.github.kittinunf.fuel", name = it, version = "-SNAPSHOT")
  }
}

Configuration

group is made up of com.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 latest master-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 also allows to build from fuel forks. If a fork's username is $yourname,

adjust group to com.github.$yourName.fuel
and look for version on https://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.

"https://httpbin.org/get"
  .httpGet()
  .responseString { request, response, result ->
    when (result) {
      is Result.Failure -> {
        val ex = result.getException()
      }
      is Result.Success -> {
        val data = result.get()
      }
    }
  }

// 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.

importre/fuel

Fuel

Features

Installation

Maven

Jitpack

Configuration

Build time-out

Forks

Quick start

Detailed usage

Basic functionality

Responses

(De)serialization

Other libraries

Credits

Licenses