a flutter library to make rest api clients more easily. inspired by java feing.
features
- facilitated json encode and decode using common interfaces.
- facilitated http errors handle.
- facilitated http header control.
- dynamic generation of urls with path and queries params.
- configurable retry attempsts on http error.
getting started
just add the package and follow the above instructions
dependencies:
hermes_http: ^1.0.0
usage
create a client class and provide default configuration and request templates on constructor;
class fruitclient {
late hermeshttpclient _client;
fruitclient() {
//creates a http client with base url and the common headers
_client = hermeshttpclient("https://www.fruityvice.com/");
_client.addheader("content-type", "application/json");
_client.addheader("connection", "keep-alive");
}
}
then create the data classes of requests and responses, and one implementation of the interfaces jsondecoder, jsonencoder for each class.
//classes that implements json parser and json encoder,
//its not mandatory parser and encoder interfaces are implemented by the data class itself.
//the interface can be implemented by another classes
class fruit implements jsondecoder<fruit>, jsonencoder<fruit> {
string genus = "";
string name = "";
int id = 0;
string family = "";
string order = "";
nutrition nutritions = nutrition();
@override
fruit fromjson(dynamic jsonmap) {
fruit fruit = fruit();
fruit.genus = jsonmap['genus'];
fruit.name = jsonmap['name'];
fruit.id = jsonmap['id'];
fruit.family = jsonmap['family'];
fruit.order = jsonmap['order'];
fruit.nutritions = nutritiondecoder().fromjson(jsonmap['nutritions']);
return fruit;
}
@override
map<string, dynamic> tojson(fruit obj) {
map<string, dynamic> map = <string, dynamic>{};
map['genus'] = obj.genus;
map['name'] = obj.name;
map['id'] = obj.id;
map['family'] = obj.family;
map['order'] = obj.order;
map['nutritions'] = nutritionencoder().tojson(obj.nutritions);
return map;
}
}
class nutrition {
num carbohydrates = 0;
num protein = 0;
num fat = 0;
num calories = 0;
num sugar = 0;
}
class nutritiondecoder extends jsondecoder<nutrition> {
@override
nutrition fromjson(jsonmap) {
nutrition nutrition = nutrition();
nutrition.carbohydrates = jsonmap['carbohydrates'];
return nutrition;
}
}
class nutritionencoder extends jsonencoder<nutrition> {
@override
map<string, dynamic> tojson(nutrition obj) {
map<string, dynamic> map = <string, dynamic>{};
map['carbohydrates'] = obj.carbohydrates;
return map;
}
}
using the data classes create the requests templates.
for each request template provide an hermesrequest<request, response> reference, either the request or response object can be void (if you want to ignore response void just pass void to).
after that instatiate the request template on constructor
the parameters are:
- hermes http client (or a custom implementation of the ihermeshttpclient)
- http method lowercase
- path with any params inside brackets ( /api/fruit/{fruitname} , /api/fruit/nutrition?min={minumunvalue}&max={maximumvalue} )
- an implementation of jsonencoder interface (use voidjsonencoder() for void values)
- an implementation of jsondecoder interface (use voidjsondecoder() for void values)
- optional named parameter maxattempts for configure retry (default 3)
- optional custom headers for the request ( map<string,string> )
class fruitclient {
late hermeshttpclient _client;
//declares a request with the request body type and the response body type
late hermesrequest<void, fruit> _getfruit;
late hermesrequest<void, list<fruit>> _getallfruit;
late hermesrequest<fruit, void> _addfruit;
fruitclient() {
//creates a http client with base url and the common headers
_client = hermeshttpclient("https://www.fruityvice.com/");
_client.addheader("content-type", "application/json");
_client.addheader("connection", "keep-alive");
//creates the request instance
_getfruit = hermesrequest(_client, 'get', '/api/fruit/{fruitname}', voidjsonencoder(), fruit());
//create the request using the class listjsondecoder to parse the json list
_getallfruit = hermesrequest(_client, 'get', '/api/fruit/all', voidjsonencoder(), listjsondecoder<fruit>(fruit()));
//create the request setting the maxattemps (retry) to only 1 (defaults 3)
_addfruit = hermesrequest(_client, 'put', '/api/fruit', fruit(), voidjsondecoder(), maxattempts: 1);
}
}
then just finish exposing methods of the client
class fruitclient {
late hermeshttpclient _client;
//declares a request with the request body type and the response body type
late hermesrequest<void, fruit> _getfruit;
late hermesrequest<void, list<fruit>> _getallfruit;
late hermesrequest<fruit, void> _addfruit;
fruitclient() {
//creates a http client with base url and the common headers
_client = hermeshttpclient("https://www.fruityvice.com/");
_client.addheader("content-type", "application/json");
_client.addheader("connection", "keep-alive");
//creates the request instance
_getfruit = hermesrequest(_client, 'get', '/api/fruit/{fruitname}', voidjsonencoder(), fruit());
//create the request using the class listjsondecoder to parse the json list
_getallfruit = hermesrequest(_client, 'get', '/api/fruit/all', voidjsonencoder(), listjsondecoder<fruit>(fruit()));
//create the request setting the maxattemps (retry) to only 1 (defaults 3)
_addfruit = hermesrequest(_client, 'put', '/api/fruit', fruit(), voidjsondecoder(), maxattempts: 1);
}
//creates a call to request
//pass any kind of param (path, query) in the path as a map
future<fruit> getfruit(string fruitname) async {
return await _getfruit.call(pathparams: { 'fruitname': fruitname });
}
future<list<fruit>> getallfruit() async {
_getallfruit.addheader("accept", "application/json"); //dinamically set a header to the request
return await _getallfruit.call();
}
future<void> addfruit(fruit fruit) async {
await _addfruit.call(body: fruit);
}
}
the full example can be found on github exemples folder.
if the http call return http status diferent of the 2xx family the following exception will be thrown
class hermesrequesterror implements exception {
int status = 0;
string body = "";
string uri = "";
string method = "";
hermesrequesterror(this.status, this.method, this.uri, this.body);
}
additional information
fell free to contribute.
Comments are closed.