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.OPTIONSFuel.request(Method.OPTIONS, "https://httpbin.org/anything")Method.TRACEFuel.request(Method.TRACE, "https://httpbin.org/anything")Method.CONNECTPATCH 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 requestParametersString 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 PATCHParameters with BodyParameterEncoder request interceptor from your FuelManager.Parameters with multipart/form-dataUploadRequest 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&...keyRequest 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:POSTPUTPATCH (actually a POST, as noted above)DELETEBody for the request. If you are looking for a multipart/form-data upload request, checkout the UploadRequest feature.application/jsonapplication/json header, you can use .jsonBody(value: String) extension to automatically do this for you.StringFileInputStreamlazy 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.HeadersHeaders companion and can be accessed (e.g. Headers.CONTENT_TYPE, Headers.ACCEPT, ...).HeaderValuesrequest[header]header: Stringrequest.header(header)header: StringHeaderValuesrequest[header] = valuesheader: String, values: Collection<*>request[header] = valueheader: String, value: Anyrequest.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: Anyrequest.header(header, value, value, ...)header: String, vararg values: AnyHeaderValuesrequest.appendHeader(pair, pair, ...)vararg pairs: Pair<String, Any>request.appendHeader(header, value)header: String, value: Anyrequest.appendHeader(header, value, value, ...)header: String, vararg values: AnyContent-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 ListRequest 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) -> DataPartrequest.add()varargs dataparts: DataPartrequest.progress(handler)hander: ProgressCallbackrequestProgress handlerDataPart from FileDataParts 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)InputStreams, 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: CharsetResponseResultOf<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: HandlerCancellableRequestresponseString(charset) { handler }charset: Charset, handler: HandlerCancellableRequestresponseObject(deserializer) { handler }deserializer: Deserializer, handler: HandlerCancellableRequestUTF-8. If you want to implement your own deserializers, scroll down to advanced usage.await(deserializer)deserializer: Deserializer<U>UawaitResult(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 UU 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.FailureFile 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) -> Filerequest.streamDestination { }(Response, Request) -> Pair<OutputStream, () -> InputStream>request.progress(handler)hander: ProgressCallbackresponseProgress 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 { }Requestresponse 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