# dio 0.0.1 A powerful Http client for Dart, which supports Interceptors, Global configuration, FormData and soon on. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir flutter pub add 'dio:0.0.1' ``` Published: 2018-04-21T17:17:44.390253Z Expected archive SHA-256: 5bc41fc87b17c446466a0d3c6bd26230e0c072e5f88ad9bc4bf26536d5eddd8b Available in cache; verification: upstream_checksum ## Direct dependencies ## Package README (untrusted upstream documentation) # dio A powerful Http client for Dart, which supports Interceptors, Global configuration, FormData, File downloading etc. and Dio is very easy to use. ### Add dependency ```yaml dependencies: dio: ^0.0.1 ``` ## Super simple to use ```dart import 'package:dio/dio.dart'; Dio dio = new Dio(); Response response=await dio.get("https://www.google.com/"); print(response.data); ``` ## Table of contents [Examples](#examples) [Dio APIs](#dio-apis) [Request Options](#request-options) [Response Schema](#response-schema) [Interceptors](#interceptors) [Handling Errors](#handling-errors) [Using application/x-www-form-urlencoded format](#using-applicationx-www-form-urlencoded-format) [Sending FormData](#sending-formdata) [Transformer](#transformer) [Set proxy and HttpClient config](#set-proxy-and-httpclient-config) [Features and bugs](#features-and-bugs) ## Examples Performing a `GET` request: ```dart Response response; response=await dio.get("/test?id=12&name=wendu") print(response.data.toString()); // Optionally the request above could also be done as response=await dio.get("/test",data:{"id":12,"name":"wendu"}) print(response.data.toString()); ``` Performing a `POST` request: ```dart response=await dio.post("/test",data:{"id":12,"name":"wendu"}) ``` Performing multiple concurrent requests: ```dart response= await Future.wait([dio.post("/info"),dio.get("/token")]); ``` Downloading a file: ```dart response=await dio.download("https://www.google.com/","./xx.html") ``` Sending FormData: ```dart FormData formData = new FormData.from({ "name": "wendux", "age": 25, }); response = await dio.post("/info", data: formData) ``` Uploading multiple files to server by FormData: ```dart FormData formData = new FormData.from({ "name": "wendux", "age": 25, "file1": new UploadFileInfo(new File("./upload.txt"), "upload1.txt") "file2": new UploadFileInfo(new File("./upload.txt"), "upload2.txt") }); response = await dio.post("/info", data: formData) ``` ## Dio APIs ### Creating an instance You can create instance of Dio with a optional `Options` object: ```dart Dio dio = new Dio; // with default Options //or Options options= new Options(baseUrl:"https://www.xx.com/api" ); Dio dio = new Dio(options); ``` The core API in Dio instance is : **Future request(String path, {data, Options options})** ```dart response=await request("/test", data: {"id":12,"name":"xx"}, new Options(method:"GET")); ``` ### Request method aliases For convenience aliases have been provided for all supported request methods. **Future get(path, {data, Options options})** **Future post(path, {data, Options options})** **Future put(path, {data, Options options})** **Future delete(path, {data, Options options})** **Future head(path, {data, Options options})** **Future put(path, {data, Options options})** **Future path(path, {data, Options options})** ## Request Options These are the available config options for making requests. Requests will default to `GET` if `method` is not specified. ```dart { /// Http method. String method; /// Request base url, it can contain sub path, like: "https://www.google.com/api/". String baseUrl; /// Http request headers. Map headers; /// Reserved, not support yet! int timeout; /// Request data, can be any type. T data; /// If the `path` starts with "http(s)", the `baseURL` will be ignored, otherwise, /// it will be combined and then resolved with the baseUrl. String path=""; /// The request Content-Type. The default value is [ContentType.JSON]. /// If you want to encode request body with "application/x-www-form-urlencoded", /// you can set `ContentType.parse("application/x-www-form-urlencoded")`, and [Dio] /// will automatically encode the request body. ContentType contentType; /// [responseType] indicates the type of data that the server will respond with /// options which defined in [ResponseType] are `JSON`, `STREAM`, `PLAIN`. /// /// The default value is `JSON`, dio will parse response string to json object automatically /// when the content-type of response is "application/json". /// /// If you want to receive response data with binary bytes, for example, /// downloading a image, use `STREAM`. /// /// If you want to receive the response data with String, use `PLAIN`. ResponseType responseType; /// Custom field that you can retrieve it later in [Interceptor]、[TransFormer] and the [Response] object. Map extra; } ``` ## Response Schema The response for a request contains the following information. ```dart { /// Response body. may have been transformed, please refer to [ResponseType]. T data; /// Response headers. HttpHeaders headers; /// The corresponding request info. Options request; /// Http status code. int statusCode; } ``` When request is succeed, you will receive the response as follows: ```dart Response response=await dio.get("https://www.google.com"); print(response.data); print(response.headers); print(response.request); print(statusCode); ``` ## Interceptors Each Dio instance has a `RequestInterceptor` and a `ResponseInterceptor`, by which you can intercept requests or responses before they are handled by `then` or `catchError`. ```dart dio.interceptor.request.onSend = (Options options){ // Do something before request is sent return options; //continue // If you want to resolve the request with some custom data， // you can return a `Response` object or return `dio.resolve(data)`. // If you want to reject the request with a error message, // you can return a `DioError` object or return `dio.reject(errMsg)` } dio.interceptor.response.onSuccess = (Response response) { // Do something with response data return response; // continue }; dio.interceptor.response.onError = (DioError e){ // Do something with response error return DioError;//continue } ``` If you may need to remove an interceptor later you can. ```dart dio.interceptor.request.onSend=null; dio.interceptor.response.onSuccess=null; dio.interceptor.response.onError=null; ``` ### Resolve and reject the request In all interceptors, you can interfere with thire execution flow. If you want to resolve the request/response with some custom data， you can return a `Response` object or return `dio.resolve(data)`. If you want to reject the request/response with a error message, you can return a `DioError` object or return `dio.reject(errMsg)` . ```dart dio.interceptor.request.onSend = (Options options){ return dio.resolve("fake data") } Response response= await dio.get("/test"); print(response.data);//"fake data" ``` ### Supports Async tasks in Interceptors Interceptors not only support synchronous tasks , but also supports asynchronous tasks, for example: ```dart dio.interceptor.request.onSend = (Options options) async{ //...If no token, request token firstly. Response response = await dio.get("/token"); //Set the token to headers options.headers["token"] = response.data["data"]["token"]; return options; //continue } ``` ### Lock/unlock the interceptors you can lock/unlock the interceptors by calling their `lock()`/`unlock` method. Once the request/response interceptor is locked, the incoming request/response will be added to a queue before they enter the interceptor, they will not be continued until the interceptor is unlocked. ```dart tokenDio=new Dio(); //Create a new instance to request the token. tokenDio.options=dio; dio.interceptor.request.onSend = (Options options) async{ // If no token, request token firstly and lock this interceptor // to prevent other request enter this interceptor. dio.interceptor.request.lock(); // We use a new Dio(to avoid dead lock) instance to request token. Response response = await tokenDio.get("/token"); //Set the token to headers options.headers["token"] = response.data["data"]["token"]; dio.interceptor.request.unlock() return options; //continue } ``` ## Handling Errors ```dart try { //404 await dio.get("https://wendux.github.io/xsddddd"); } on DioError catch(e) { // The request was made and the server responded with a status code // that falls out of the range of 2xx and is also not 304. if(e.response) { print(e.response.data) print(e.response.headers) print(e.response.request) } else{ // Something happened in setting up or sending the request that triggered an Error print(e.request) print(e.message) } } ``` ## Using application/x-www-form-urlencoded format By default, Dio serializes request data(except String type) to `JSON`. To send data in the `application/x-www-form-urlencoded` format instead, you can : ```dart //Instance level dio.options.contentType=ContentType.parse("application/x-www-form-urlencoded"); //or works once dio.post("/info",data:{"id":5}, options: new Options(contentType:ContentType.parse("application/x-www-form-urlencoded"))) ``` ## Sending FormData You can also send FormData with Dio, which will send data in the `multipart/form-data`, and it supports upload files. ```dart FormData formData = new FormData.from({ "name": "wendux", "age": 25, "file": new UploadFileInfo(new File("./example/upload.txt"), "upload.txt") }); response = await dio.post("/info", data: formData) ``` > Note: Just the post method suppots FormData. ## Transformer `TransFormer` allows changes to the request/response data before it is sent/received to/from the server. This is only applicable for request methods 'PUT', 'POST', and 'PATCH'. Dio has already implemented a `DefaultTransformer`, and as the default `TransFormer`. If you want to custom the transformation of request/response data, you can provide a `TransFormer` by your self, and replace the `DefaultTransformer` by setting the `dio.transformer`. ## Set proxy and HttpClient config Dio use HttpClient to send http request, so you can config the `dio.httpClient` to support `porxy`, for example: ```dart dio.httpClient.findProxy = (uri) { //proxy all request to localhost:8888 return "PROXY localhost:8888"; }; ``` ## Features and bugs Please file feature requests and bugs at the [issue tracker][tracker]. [tracker]: https://github.com/wendux/dio/issues ## Changelog ## 0.0.1 - Initial version, created by Stagehand