albodelu / fuel

The easiest HTTP networking library for Kotlin/Android

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

You can download and install Fuel with Maven and Gradle. The core package has the following dependencies:

• Kotlin - 1.3.0
• Coroutine - 1.0.0

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

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.

Basic functionality

• fuel: Basic usage
• fuel-coroutines: Execution with coroutines
• fuel-android: Android usage

Responses

• fuel-livedata: Responses as LiveData
• fuel-rxjava: Responses as Single
• fuel-reactor: Responses as Mono

(De)serialization

• fuel-gson: (De)serialization with Gson
• fuel-kotlinx-serialization: (De)serialization with KotlinX Serialization
• fuel-forge: Deserialization with Forge
• fuel-jackson: Deserialization with Jackson
• fuel-moshi: Deserialization with Moshi
• fuel-json: Deserialization with Json

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.