Step 1. Add the JitPack repository to your build file
Add it in your root build.gradle at the end of repositories:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Add it in your build.sbt at the end of resolvers:
resolvers += "jitpack" at "https://jitpack.io"
Add it in your project.clj at the end of repositories:
:repositories [["jitpack" "https://jitpack.io"]]
Step 2. Add the dependency
dependencies {
implementation 'com.github.carmas123:fuel:1.2.1'
}
<dependency>
<groupId>com.github.carmas123</groupId>
<artifactId>fuel</artifactId>
<version>1.2.1</version>
</dependency>
libraryDependencies += "com.github.carmas123" % "fuel" % "1.2.1"
:dependencies [[com.github.carmas123/fuel "1.2.1"]]
The easiest HTTP networking library for Kotlin/Android.
FuelManager
repositories {
jcenter()
}
dependencies {
compile 'com.github.kittinunf.fuel:fuel:1.3.0' //for JVM
compile 'com.github.kittinunf.fuel:fuel-android:1.3.0' //for Android
compile 'com.github.kittinunf.fuel:fuel-rxjava:1.3.0' //for RxJava support
}
//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
})
}
//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
}
});
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.
val (request, response, result) = "http://httpbin.org/get".httpGet().responseString() // result is Result<String, FuelError>
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) {
}
Fuel.get("http://httpbin.org/get").response { request, response, result ->
println(request)
println(response)
val (bytes, error) = result
if (bytes != null) {
println(bytes)
}
}
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.
fun response(handler: (Request, Response, Result<ByteArray, FuelError>) -> Unit)
fun responseString(handler: (Request, Response, Result<String, FuelError>) -> Unit)
fun responseJson(handler: (Request, Response, Result<Json, FuelError>) -> Unit)
val jsonObject = json.obj() //JSONObject
val jsonArray = json.array() //JSONArray
fun <T> responseObject(deserializer: ResponseDeserializable<T>, handler: (Request, Response, Result<T, FuelError>) -> Unit)
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 ->
}
Fuel.put("http://httpbin.org/put").response { request, response, result ->
}
Fuel.delete("http://httpbin.org/delete").response { request, response, result ->
}
Fuel.head("http://httpbin.org/get").response { request, response, result ->
// request body should be empty.
}
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)
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"
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
}
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
}
Default timeout for a request is 15000 milliseconds. Default read timeout for a request is 15000 milliseconds.
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 -> }
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
}
});
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 -> {
}
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
}
val username = "username"
val password = "abcd1234"
Fuel.get("http://httpbin.org/basic-auth/$user/$password").authenticate(username, password).response { request, response, result ->
}
cancel
on the request objectval 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
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()
//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)
}
public fun deserialize(bytes: ByteArray): T?
public fun deserialize(inputStream: InputStream): T?
public fun deserialize(reader: Reader): T?
public fun deserialize(content: String): T?
object Windows1255StringDeserializer : ResponseDeserializable<String> {
override fun deserialize(bytes: ByteArray): String {
return String(bytes, "windows-1255")
}
}
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"
responseInterceptors
such asinline 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
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()
"http://www.example.com/photos/1".httpGet().rx_object(Photo.Deserializer()).subscribe {
//do something
}
Request
that provide RxJava Observable<T>
as return type.fun Request.rx_response(): Observable<Pair<Response, ByteArray>>
fun Request.rx_responseString(charset: Charset): Observable<Pair<Response, String>>
fun <T : Any> Request.rx_responseObject(deserializable: Deserializable<T>): Observable<Pair<Response, T>>
fun Request.rx_data(): Observable<ByteArray>
fun Request.rx_string(charset: Charset): Observable<String>
fun <T : Any> Request.rx_object(deserializable: Deserializable<T>): Observable<T>
If you like Fuel, you might also like other libraries;
Fuel is brought to you by contributors.
Fuel is released under the MIT license.