Fuel
. The documentation outlined here touches most subjects and functions but is not exhaustive.Fuel
with Maven
and Gradle
. The core package has the following dependencies:Fuel
, a FuelManager
instance or the string extensions.Fuel
/FuelManager
methodMethod.GET
"https://httpbin.org/get".httpGet()
Fuel.get("https://httpbin.org/get")
Method.POST
"https://httpbin.org/post".httpPost()
Fuel.post("https://httpbin.org/post")
Method.PUT
"https://httpbin.org/put".httpPut()
Fuel.put("https://httpbin.org/put")
Method.PATCH
"https://httpbin.org/patch".httpPatch()
Fuel.patch("https://httpbin.org/patch")
Method.HEAD
"https://httpbin.org/get".httpHead()
Fuel.head("https://httpbin.org/get")
Method.OPTIONS
Fuel.request(Method.OPTIONS, "https://httpbin.org/anything")
Method.TRACE
Fuel.request(Method.TRACE, "https://httpbin.org/anything")
Method.CONNECT
PATCH
requestsclient
is HttpClient
which is a thin wrapper over java.net.HttpUrlConnection
. java.net.HttpUrlConnection
does not support a PATCH
method. HttpClient
converts PATCH
requests to a POST
request and adds a X-HTTP-Method-Override: PATCH
header. While this is a semi-standard industry practice not all APIs are configured to accept this header by default.1.16.x
you can opt-in to forcing a HTTP Method on the java.net.HttpUrlConnnection
instance using reflection.CONNECT
requestParameters
String
extensions listed above, as well as the Fuel
and FuelManager
calls accept a parameter parameters: Parameters
.GET
and DELETE
requestx-www-form-urlencoded
for PUT
, POST
and PATCH
Parameters
with Body
ParameterEncoder
request interceptor from your FuelManager
.Parameters
with multipart/form-data
UploadRequest
handles encoding parameters in the body. Therefore by default, parameter encoding is ignored by ParameterEncoder
if the content type is multipart/form-data
.Parameters
with empty, array, list or null valueskey[]=value1&key[]=value2&...
key[]=value1&key[]=value2&...
key
Request
bodyRequest
is sent. However, if you pass in an in-memory value such as a ByteArray
or String
, Fuel
uses RepeatableBody
, which are kept into memory until the Request
is dereferenced.Client
, bodies are supported for:POST
PUT
PATCH
(actually a POST
, as noted above)DELETE
Body
for the request. If you are looking for a multipart/form-data
upload request, checkout the UploadRequest
feature.application/json
application/json
header, you can use .jsonBody(value: String)
extension to automatically do this for you.String
File
InputStream
lazy
source (InputStream
)BodyCallback
:RepeatableBody
, and only if the status code is 307 or 308, as per the RFCs. In order to use a RepeatableBody
, pass in a String
or ByteArray
as body, or explicitely set repeatable = true
for the fun body(...)
call.Headers
Headers
companion and can be accessed (e.g. Headers.CONTENT_TYPE
, Headers.ACCEPT
, ...).HeaderValues
request[header]
header: String
request.header(header)
header: String
HeaderValues
request[header] = values
header: String
, values: Collection<*>
request[header] = value
header: String
, value: Any
request.header(map)
map: Map<String, Any>
request.header(pair, pair, ...)
vararg pairs: Pair<String, Any>
request.header(header, values)
header: String, values: Collection<*>
request.header(header, value)
header: String, value: Any
request.header(header, value, value, ...)
header: String, vararg values: Any
HeaderValues
request.appendHeader(pair, pair, ...)
vararg pairs: Pair<String, Any>
request.appendHeader(header, value)
header: String, value: Any
request.appendHeader(header, value, value, ...)
header: String, vararg values: Any
Content-Type
.FuelManager
base headers vs. Request
headersbaseHeaders
set through a FuelManager
are only applied to a Request
if that request does not have that specific header set yet. There is no appending logic. If you set a header it will overwrite the base value.Client
headers vs. Request
headersClient
can add, remove or transform HeaderValues
before it sends the Request
or after it receives the Response
. The default Client
for example sets TE
values.HeaderValues
values are List
Request
is made, the default Client
collapses the multiple values, if allowed by the RFCs, into a single header value delimited by a separator for that header. Headers that can only be set once will use the last value by default and ignore earlier set values.Request
using the .authentication()
feature. By default, authentication
is passed on when using the default redirectResponseInterceptor
(which is enabled by default), unless it is redirecting to a different host. You can remove this behaviour by implementing your own redirection logic.When you call.authentication()
, a few extra functions are available. If you call a regular function (e.g..header()
) the extra functions are no longer available, but you can safely call.authentication()
again without losing any previous calls.
Progress
callbacks when uploading or downloading a body; the Connection
header does not support progress (which is the only thing that is sent if there are no bodies). You can have as many progress handlers of each type as you like.E/NotificationService: Package enqueue rate is 10.062265. Shedding events. package=...
.Body
or Response
Body
report their total size. If the size is not known, the current size will be reported. This means that you will constantly get an increasing amount of totalBytes that equals readBytes.multipart/form-data
(UploadRequest
).upload()
feature. You can turn any Request
into a upload request by calling .upload()
or call .upload(method = Method.POST)
directly onto Fuel
/ FuelManager
.When you call.upload()
, a few extra functions are available. If you call a regular function (e.g..header()
) the extra functions are no longer available, but you can safely call.upload()
again without losing any previous calls.
request.add { }
varargs dataparts: (Request) -> DataPart
request.add()
varargs dataparts: DataPart
request.progress(handler)
hander: ProgressCallback
requestProgress
handlerDataPart
from File
DataPart
s that are sources from a File
, you can use FileDataPart
, which takes a file: File
. There are some sane defaults for the field name name: String
, and remote file name filename: String
, as well as the Content-Type
and Content-Disposition
fields, but you can override them.files
, use the array notation:name
to multiple parts.FileDataPart.from(directory: , filename: , ...args)
to create a FileDataPart
from String
arguments.DataPart
from inline contentDataPart
. You can do this with InlineDataPart
:filename
is not mandatory and is empty by default; the contentType
is text/plain
by default.DataPart
from InputStream
(formely Blob
)InputStream
s, which you can do using BlobDataPart
:contentLength
to a positive integer, your entire Request
Content-Length
will be undeterminable and the default HttpClient
will switch to chunked streaming mode with an arbitrary stream buffer size.add
. The parameters are encoded as parts!Fuel
both synchronously and a-synchronously, with support for coroutines.response()
ResponseResultOf<ByteArray>
responseString(charset)
charset: Charset
ResponseResultOf<String>
responseObject(deserializer)
deserializer: Deserializer<U>
ResponseResultOf<U>
UTF-8
. If you want to implement your own deserializers, scroll down to advanced usage.response() { handler }
handler: Handler
CancellableRequest
responseString(charset) { handler }
charset: Charset, handler: Handler
CancellableRequest
responseObject(deserializer) { handler }
deserializer: Deserializer, handler: Handler
CancellableRequest
UTF-8
. If you want to implement your own deserializers, scroll down to advanced usage.await(deserializer)
deserializer: Deserializer<U>
U
awaitResult(deserializer)
deserializer: Deserializer<U>
Result<U, FuelError>
awaitResponse(deserializer)
deserializer: Deserializer<U>
ResponseOf<U>
awaitResponseResult(deserializer)
deserializer: Deserializer<U>
ResponseResultOf<U>
fuel-coroutines
, more response/await functions are available.ResponseResultOf<U>
type is a Triple
of the Request
, Response
and a Result<U, FuelError>
ResponseOf<U>
type is a Triple
of the Request
, Response
and a U
; errors are thrownResult<U, FuelError>
type is a non-throwing wrapper around U
U
type doesn't wrap anything; errors are thrownresponseXXX
functions that accept a Handler
:Handler<T>
success
with an instance of T
or failure
on errorsResponseHandler<T>
success
with Request
, Response
and an instance of T
, or failure
or errorsResultHandler<T>
Result<T, FuelError>
ResponseResultHandler<T>
Request
Response
and Result<T, FuelError>
Result
yourself using a ResultHandler
or ResponseResultHandler
, or define dedicated callbacks in case of success or failure.Result<T, FuelError>
fold
] and define a tranformation function for both cases that results in the same return type,when
checking whether it is Result.Success
or Result.Failure
File
or OutputStream
)Body
to a file using the .download()
feature. You can turn any Request
into a download request by calling .download()
or call .download(method = Method.GET)
directly onto Fuel
/ FuelManager
.When you call.download()
, a few extra functions are available. If you call a regular function (e.g..header()
) the extra functions are no longer available, but you can safely call.download()
again without losing any previous calls.
request.fileDestination { }
(Response, Request) -> File
request.streamDestination { }
(Response, Request) -> Pair<OutputStream, () -> InputStream>
request.progress(handler)
hander: ProgressCallback
responseProgress
handlerstream
variant expects your callback to provide a Pair
with both the OutputStream
to write too, as well as a callback that gives an InputStream
, or raises an error.OutputStream
is always closed after the body has been written. Make sure you wrap whatever functionality you need on top of the stream and don't rely on the stream to remain open.() -> InputStream
replaces the body after the current body has been written to the OutputStream
. It is used to make sure you can also retrieve the body via the response
/ await
method results. If you don't want the body to be readable after downloading it, you have to do two things:EmptyDeserializer
with await(deserializer)
or one of the response(deserializer)
variantsInputStream
callback that throws
or returns an empty InputStream
.request.streamDestination { }
instead of request.fileDestination { }
Request
response
functions called with a handler
are async and return a CancellableRequest
. These requests expose a few extra functions that can be used to control the Future
that should resolve a response:CancellableRequest
because, for example, you are adding this logic in an Interceptor
, a generic Queue
, or a ProgressCallback
, you can call tryCancel()
which returns true if it was cancelled and false otherwise. At this moment blocking
requests can not be cancelled.baseHeaders
is to manage common HTTP header pairs in format of Map<String, String>
.Headers
can be added to a request via various methods includingappendHeader
variant to append values to existing values.mapOf
overwrote, and varargs pair
did not, but this was confusing. In 2.0, this issue has been fixed and improved so it works as expected.Headers.Companion
and can be used instead of literal strings. This is an encouraged way to configure your header in 2.x.y.FuelManager.instance
to manage global configurations.FuelManager()
basePath
is used to manage common root path. Great usage is for your static API endpoint.baseParams
is used to manage common key=value
query param, which will be automatically included in all of your subsequent requests in format of Parameters
(Any
is converted to String
by toString()
method)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.HttpUrlConnection
. 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.responseInterceptors
such as