v0.1 alpha (#2)

Author: f3ath

.gitignore

@@ -1,4 +1,5 @@
-# See https://www.dartlang.org/guides/libraries/private-files
+# See https://www.dartlang.org/guides/libraries
+/private-files
 
 # Files and directories created by pub
 .dart_tool/

README.md

@@ -1,38 +1,18 @@
-# [JSON:API](http://jsonapi.org) v1.0 HTTP Client
+# Implementation of [JSON:API v1.0](http://jsonapi.org) in Dart
 
-This is a super simple implementation of JSON:API Client.
+**This is a work in progress. The API may change.**
 
-### Usage example
-```dart
-import 'package:json_api/json_api.dart';
-import 'package:json_api_document/json_api_document.dart';
+## General architecture
 
-void main() async {
-  final client = JsonApiClient(baseUrl: 'http://localhost:8888');
-  final response = await client.fetchResource('/example');
-  print((response.document as DataDocument).data.resources.first.attributes); // Attributes{message: Hello world!}
-}
-```
+The library consists of three major parts: Document, Server, and Client.
 
-### Supported methods
+### Document
+This is the core part. 
+It describes JSON:API Document and its components (e.g. Resource Objects, Identifiers, Relationships, Links), 
+validation rules (naming conventions, full linkage), and service discovery (e.g. fetching pages and related resources).
 
-- `addToMany`
-Adds the identifiers to the to-many relationship via POST request to the url.
-- `createResource`
-Creates a new resource sending a POST request to the url.
-- `deleteResource`
-Deletes the resource sending a DELETE request to the url.
-- `deleteToMany`
-Deletes the identifiers from the to-many relationship via DELETE request to the url.
-- `deleteToOne`
-Removes a to-one relationship sending PATCH request with "null" data to the url.
-- `fetchRelationship`
-Fetches a Document containing identifier(s) from the given url.
-- `fetchResource`
-Fetches a Document containing resource(s) from the given url.
-- `setToMany`
-Updates (replaces!) a to-many relationship sending the identifiers via PATCH request to the url.
-- `setToOne`
-Creates or updates a to-one relationship sending a corresponding identifier via PATCH request to the url.
-- `updateResource`
-Updates the resource sending a PATCH request to the url.
+### Client
+This is a JSON:API client based on Dart's native HttpClient.
+
+### Server
+A JSON:API server. Routes requests, builds responses.

example/example.dart

@@ -0,0 +1,10 @@
+import 'dart:io';
+
+import 'server/server.dart';
+
+void main() async {
+  final addr = InternetAddress.loopbackIPv4;
+  final port = 8080;
+  await createServer().start(addr, port);
+  print('Listening on ${addr.host}:$port');
+}

example/server.dart

@@ -0,0 +1,49 @@
+import 'package:json_api/document.dart';
+import 'package:json_api/server.dart';
+
+import 'dao.dart';
+
+class CarsController implements ResourceController {
+  final Map<String, DAO> dao;
+
+  CarsController(this.dao);
+
+  @override
+  bool supports(String type) => dao.containsKey(type);
+
+  Future<Collection<Resource>> fetchCollection(
+      String type, Map<String, String> queryParameters) async {
+    final page = NumberedPage.fromQueryParameters(queryParameters,
+        total: dao[type].length);
+    return Collection(
+        dao[type]
+            .fetchCollection(offset: page.number - 1)
+            .map(dao[type].toResource),
+        page: page);
+  }
+
+  @override
+  Stream<Resource> fetchResources(Iterable<Identifier> ids) async* {
+    for (final id in ids) {
+      final obj = dao[id.type].fetchById(id.id);
+      yield obj == null ? null : dao[id.type].toResource(obj);
+    }
+  }
+
+  @override
+  Future createResource(String type, Resource resource) async {
+    final obj = dao[type].fromResource(resource);
+    dao[type].insert(obj);
+    return null;
+  }
+
+  @override
+  Future mergeToMany(Identifier id, String name, ToMany rel) async {
+    final obj = dao[id.type].fetchById(id.id);
+    rel.identifiers
+        .map((id) => dao[id.type].fetchById(id.id))
+        .forEach((related) => dao[id.type].addRelationship(obj, name, related));
+
+    return null;
+  }
+}

examples/server.dart

@@ -0,0 +1,77 @@
+import 'package:json_api/document.dart';
+
+import 'model.dart';
+
+abstract class DAO<T extends HasId> {
+  final collection = <String, T>{};
+
+  int get length => collection.length;
+
+  Resource toResource(T t);
+
+  Relationship relationship(String name, T t) {
+    throw ArgumentError();
+  }
+
+  Map<String, Relationship> relationships(List<String> names, T t) =>
+      Map.fromIterables(names, names.map((_) => relationship(_, t)));
+
+  T fetchById(String id) => collection[id];
+
+  void insert(T t) => collection[t.id] = t;
+
+  Iterable<T> fetchCollection({int offset = 0, int limit = 1}) =>
+      collection.values.skip(offset).take(limit);
+
+  HasId fromResource(Resource r);
+
+  addRelationship(T t, String name, HasId related) {}
+}
+
+class CarDAO extends DAO<Car> {
+  Resource toResource(Car _) =>
+      Resource('cars', _.id, attributes: {'name': _.name});
+
+  @override
+  HasId fromResource(Resource r) => Car(r.id, r.attributes['name']);
+}
+
+class CityDAO extends DAO<City> {
+  Resource toResource(City _) =>
+      Resource('cities', _.id, attributes: {'name': _.name});
+
+  @override
+  HasId fromResource(Resource r) => City(r.id, r.attributes['name']);
+}
+
+class BrandDAO extends DAO<Brand> {
+  Resource toResource(Brand brand) => Resource('brands', brand.id,
+      attributes: {'name': brand.name},
+      relationships: relationships(['headquarters', 'models'], brand));
+
+  Relationship relationship(String name, Brand brand) {
+    switch (name) {
+      case 'headquarters':
+        return ToOne(brand.headquarters == null
+            ? null
+            : Identifier('cities', brand.headquarters));
+      case 'models':
+        return ToMany(brand.models.map((_) => Identifier('cars', _)));
+    }
+    throw ArgumentError();
+  }
+
+  @override
+  HasId fromResource(Resource r) => Brand(r.id, r.attributes['name']);
+
+  @override
+  addRelationship(Brand obj, String name, HasId related) {
+    switch (name) {
+      case 'models':
+        obj.models.add(related.id);
+        break;
+      default:
+        throw ArgumentError.value(name, 'name');
+    }
+  }
+}

examples/server/controller.dart

@@ -0,0 +1,26 @@
+abstract class HasId {
+  String get id;
+}
+
+class Brand implements HasId {
+  final String name;
+  final String id;
+  final String headquarters;
+  final List<String> models;
+
+  Brand(this.id, this.name, {this.headquarters, this.models = const []});
+}
+
+class City implements HasId {
+  final String name;
+  final String id;
+
+  City(this.id, this.name);
+}
+
+class Car implements HasId {
+  final String name;
+  final String id;
+
+  Car(this.id, this.name);
+}

examples/server/dao.dart

@@ -0,0 +1,36 @@
+import 'package:json_api/simple_server.dart';
+
+import 'controller.dart';
+import 'dao.dart';
+import 'model.dart';
+
+SimpleServer createServer() {
+  final cars = CarDAO();
+  [
+    Car('1', 'Roadster'),
+    Car('2', 'Model S'),
+    Car('3', 'Model X'),
+    Car('4', 'Model 3'),
+  ].forEach(cars.insert);
+
+  final cities = CityDAO();
+  [
+    City('1', 'Munich'),
+    City('2', 'Palo Alto'),
+    City('3', 'Ingolstadt'),
+  ].forEach(cities.insert);
+
+  final brands = BrandDAO();
+  [
+    Brand('1', 'Tesla', headquarters: '2', models: ['1', '2', '3', '4']),
+    Brand('2', 'BMW', headquarters: '1'),
+    Brand('3', 'Audi', headquarters: '3'),
+    Brand('4', 'Ford'),
+    Brand('5', 'Toyota')
+  ].forEach(brands.insert);
+
+  final controller =
+      CarsController({'brands': brands, 'cities': cities, 'cars': cars});
+
+  return SimpleServer(controller);
+}

examples/server/model.dart

@@ -0,0 +1,21 @@
+import 'package:json_api/document.dart';
+
+export 'package:json_api/src/client/dart_http_client.dart';
+
+abstract class Client implements ResourceFetcher, CollectionFetcher {
+  Future<Response<CollectionDocument>> fetchCollection(Uri uri,
+      {Map<String, String> headers});
+
+  Future<Response<ResourceDocument>> fetchResource(Uri uri,
+      {Map<String, String> headers});
+
+  Future<Response<ToOne>> fetchToOne(Uri uri, {Map<String, String> headers});
+
+  Future<Response<ToMany>> fetchToMany(Uri uri, {Map<String, String> headers});
+
+  Future<Response<ResourceDocument>> createResource(Uri uri, Resource r,
+      {Map<String, String> headers});
+
+  Future<Response<ToMany>> addToMany(Uri uri, Iterable<Identifier> ids,
+      {Map<String, String> headers});
+}