rest_data

Description:

rest data

rest_data #
The goal of this package is to make interaction with your REST APIs pleasant and concise. It currently supports JSON:API-compliant REST APIs, but can be extended to support more formats - and you're encouraged to contribute!

Introduction #
rest_data is inspired by ember-data so it's based on 3 main abstractions:

Model: represents a single REST resource, with its attributes and relationships.
Serializer: takes care of transforming Model objects into your REST API payloads format (usually JSON), and vice-versa.
Adapter: provides methods to read/write model objects to your REST APIs; it maps to ember-data's Store but we choose to not adopt the name Store in order to avoid conflict with the popular dart package redux.

Usage with a JSON:API backend #
Instantiating the Adapter #
Create your Adapter as follows:
Adapter adapter = JsonApiAdapter('host.example.com', '/path/to/rest/api');
copied to clipboard
This is designed to be a long-lived object: a good practice is to wrap it in a singleton class to be used across the whole app, or to make it available throughout your app via Dependency Injection.
Defining Models #
For each of your REST API resources, you should define a model class extending JsonApiModel which provides the following getters:

Map<String, dynamic> get attributes see specs
Map<String, dynamic> get relationships see specs
Iterable<dynamic> get included see specs
Iterable<dynamic> get errors see specs

together with helper methods (e.g. idFor(), idsFor(), typeFor(), setHasOne() etc. - see the source for more details).
Example model follows:
class Address extends JsonApiModel {
// Constructors

Address(JsonApiDocument doc) : super(doc);
Address.init(String type) : super.init(type);

// Attributes

String get street => getAttribute<String>('street');
set street(String value) => setAttribute<String>('street', value);

String get city => getAttribute<String>('city');
set city(String value) => setAttribute<String>('city', value);

String get zip => getAttribute<String>('zip');
set zip(String value) => setAttribute<String>('zip', value);

// Has-One Relationships

String get countryId => idFor('country');
set country(Country model) => setHasOne('country', model);
}

class Country extends JsonApiModel {
Country(JsonApiDocument doc) : super(doc);
}
copied to clipboard
Reading #
Invoking REST APIs is as simple as calling async methods on your adapter object. Such methods return one or more JsonApiDocument objects, which can be used to build your model objects.
Finding a specific record
var address = Address(await adapter.find('addresses', '1'));
copied to clipboard
Will send the request: GET /addresses/1.
Finding all records
Iterable<Country> countries =
adapter.findAll('countries')
.map<Country>((jsonApiDoc) => Country(jsonApiDoc));
copied to clipboard
Will send the request: GET /countries.
Finding N specific records
Iterable<Address> addresses =
(await adapter.findMany('addresses', ['1', '2', '3']))
.map<Address>((jsonApiDoc) => Address(jsonApiDoc));
copied to clipboard
GET /addresses?filter[id]=1,2,3
Querying
Iterable<Address> addresses =
(await adapter.query('addresses', {'q': 'miami'}))
.map<Address>((jsonApiDoc) => Address(jsonApiDoc));
copied to clipboard
GET /addresses?filter[q]=miami
Writing #
Create
You'll start with an empty model object, whose attributes and relationships will be set based on user input:
var address = Address.init();
address.street = '9674 Northwest 10th Avenue';
address.city = 'Miami';
address.zip = '33150';
address.country = Country.peek('US'); // Assume all countries are cached, see "Caching" section later
copied to clipboard
To persist your model on your REST API backend, just invoke the Adapter's save() method, which will return a new Address object:
var savedAddress = Address(await adapter.save(endpoint, address.jsonApiDoc));
copied to clipboard
The above line will send the request: POST /addresses with the address model object serialized as a JSON:API Document.
Update
Assume you have an existing model object, and you edit some attributes based on user input:
var address = Address(await adapter.find('addresses', '1'));
address.street = '9674 Northwest 10th Avenue';
address.zip = '33150';
copied to clipboard
To persist your model on your REST API backend, just invoke the Adapter's save() method, which will return a new Address object:
var savedAddress = Address(await adapter.save(endpoint, address.jsonApiDoc));
copied to clipboard
The above line will send the request: PUT /addresses with the address model object serialized as a JSON:API Document.
Caching #
JsonApiAdapter comes with a basic caching mechanism built-in: a simple Map in-memory. Models fetched from the backend are automatically cached on any read request, and the cached ones are returned on subsequent read requests for the same model id.
When you only want already cached data, you can use Adapter's methods starting with the peek prefix.
Invalidation must be handled manually, passing forceReload = true to find* methods.