V3 Relese (#69)

Author: f3ath

.travis.yml

@@ -4,6 +4,7 @@ dart:
   - dev
   - "2.6.0"
   - "2.6.1"
+  - "2.7.0"
 dart_task:
   - test: --platform vm
   - test: --platform chrome

CHANGELOG.md

@@ -5,25 +5,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [3.0.0] - 2019-12-17
 ### Added
 - Support for custom non-standard links ([#61](https://github.com/f3ath/json-api-dart/issues/61))
 - Client supports `jsonapi` key in outgoing requests.
 - `Document.contentType` constant.
 - `IdentifierObject.fromIdentifier` factory method
 
 ### Changed
-Most of this changes are **BC-BREAKING**.
+Most of the changes are **BC-BREAKING**.
 - `URLBuilder` was renamed to `UrlFactory`.
 - `DocumentBuilder` was split into `ServerDocumentFactory` and `ClientDocumentFactory`. Some methods were renamed.
 - Static `decodeJson` methods were renamed to `fromJson`.
 - `Identifier.equals` now requires the runtime type to be exactly the same.
-- `Link.decodeJsonMap` was renamed to `mapFromJson`
-- `TargetMatcher` changed its signature.
+- `Link.decodeJsonMap` was renamed to `mapFromJson`.
+- The signature of `TargetMatcher`.
+- The signature of `Controller`.
+- `Server` was renamed to `JsonApiServer`.
+- `Pagination` was renamed to `PaginationStrategy`.
 
 ### Removed
 - (Server) `ResourceTarget`, `CollectionTarget`, `RelationshipTarget`  classes.
 - `QueryParameters` interface.
 - `Router` class.
+- `Query` class.
 
 ## [2.1.0] - 2019-12-04
 ### Added
@@ -112,7 +117,8 @@ Most of this changes are **BC-BREAKING**.
 ### Added
 - Client: fetch resources, collections, related resources and relationships
 
-[Unreleased]: https://github.com/f3ath/json-api-dart/compare/2.1.0...HEAD
+[Unreleased]: https://github.com/f3ath/json-api-dart/compare/3.0.0...HEAD
+[3.0.0]: https://github.com/f3ath/json-api-dart/compare/2.1.0...3.0.0
 [2.1.0]: https://github.com/f3ath/json-api-dart/compare/2.0.3...2.1.0
 [2.0.3]: https://github.com/f3ath/json-api-dart/compare/2.0.2...2.0.3
 [2.0.2]: https://github.com/f3ath/json-api-dart/compare/2.0.1...2.0.2

CONTRIBUTING.md

@@ -1,162 +1,14 @@
-[JSON:API](http://jsonapi.org) is a specification for building APIs in JSON. 
-
-# Client
-Quick usage example:
-```dart
-import 'package:http/http.dart';
-import 'package:json_api/json_api.dart';
-
-void main() async {
-  final httpClient = Client();
-  final jsonApiClient = JsonApiClient(httpClient);
-  final companiesUri = Uri.parse('http://localhost:8080/companies');
-  final response = await jsonApiClient.fetchCollection(companiesUri);
-  httpClient.close();
-  print('Status: ${response.status}');
-  print('Headers: ${response.headers}');
-
-  final resource = response.data.unwrap().first;
-
-  print('The collection page size is ${response.data.collection.length}');
-  print('The first element is ${resource}');
-  print('Attributes:');
-  resource.attributes.forEach((k, v) => print('$k=$v'));
-  print('Relationships:');
-  resource.toOne.forEach((k, v) => print('$k=$v'));
-  resource.toMany.forEach((k, v) => print('$k=$v'));
-}
-```
-To see this in action:
- 
- 1. start the server:
-```
-$ dart example/cars_server.dart
-Listening on 127.0.0.1:8080
-```
-2. run the script:
-```
-$ dart example/fetch_collection.dart 
-Status: 200
-Headers: {x-frame-options: SAMEORIGIN, content-type: application/vnd.api+json, x-xss-protection: 1; mode=block, x-content-type-options: nosniff, transfer-encoding: chunked, access-control-allow-origin: *}
-The collection page size is 1
-The first element is Resource(companies:1)
-Attributes:
-name=Tesla
-nasdaq=null
-updatedAt=2019-07-07T13:08:18.125737
-Relationships:
-hq=Identifier(cities:2)
-models=[Identifier(models:1), Identifier(models:2), Identifier(models:3), Identifier(models:4)]
-```
-
-The client provides a set of methods to deal with resources and relationships.
-- Fetching
-    - [fetchCollection](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/fetchCollection.html) - resource collection, either primary or related
-    - [fetchResource](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/fetchResource.html) - a single resource, either primary or related
-    - [fetchRelationship](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/fetchRelationship.html) - a generic relationship (either to-one, to-many or even incomplete)
-    - [fetchToOne](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/fetchToOne.html) - a to-one relationship
-    - [fetchToMany](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/fetchToMany.html) - a to-many relationship
-- Manipulating resources
-    - [createResource](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/createResource.html) - creates a new primary resource
-    - [updateResource](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/updateResource.html) - updates the existing resource by its type and id
-    - [deleteResource](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/deleteResource.html) - deletes the existing resource
-- Manipulating relationships
-    - [replaceToOne](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/replaceToOne.html) - replaces the existing to-one relationship with a new resource identifier
-    - [deleteToOne](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/deleteToOne.html) - deletes the existing to-one relationship by setting the resource identifier to null
-    - [replaceToMany](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/replaceToMany.html) - replaces the existing to-many relationship with the given set of resource identifiers
-    - [addToMany](https://pub.dev/documentation/json_api/latest/client/JsonApiClient/addToMany.html) - adds the given identifiers to the existing to-many relationship
-    
-These methods accept the target URI and the object to update (except for fetch and delete requests).
-You can also pass an optional map of HTTP headers, e.g. for authentication. The return value
-is a [Response] object. 
-
-You can get the status of the [Response] from either [Response.status] or one of the following properties: 
-- [Response.isSuccessful]
-- [Response.isFailed]
-- [Response.isAsync] (see [Asynchronous Processing])
-
-The Response also contains the raw [Response.status] and a map of HTTP headers.
-Two headers used by JSON:API can be accessed directly for your convenience:
-- [Response.location] holds the `Location` header used in creation requests
-- [Response.contentLocation] holds the `Content-Location` header used for [Asynchronous Processing]
-
-The most important part of the Response is the [Response.document] containing the JSON:API document sent by the server (if any). 
-If the document has the Primary Data, you can use [Response.data] shortcut to access it directly.
-
-#### Included resources
-If you requested related resources to be included in the response (see [Compound Documents]) and the server fulfilled
-your request, the [PrimaryData.included] property will contain them.
-
-#### Errors
-For unsuccessful operations the [Response.data] property will be null. 
-If the server decided to include the error details in the response, those can be found in the  [Document.errors] property.
-
-#### Async processing
-Some servers may support [Asynchronous Processing].
-When the server responds with `202 Accepted`, the client expects the Primary Data to always be a Resource (usually
-representing a job queue). In this case, [Response.document] and [Response.data] will be null. Instead, 
-the response document will be placed to [Response.asyncDocument] (and [Response.asyncData]). 
-Also in this case the [Response.contentLocation]
-will point to the job queue resource. You can fetch the job queue resource periodically and check
-the type of the returned resource. Once the operation is complete, the request will return the created resource.
-
-#### Adding JSON:API Object
-It is possible to add the [JSON:API Object] to all documents sent by the [JsonApiClient]. To do so, pass the
-pre-configured [DocumentFactory] to the [JsonApiClient]:
-```dart
-import 'package:http/http.dart';
-import 'package:json_api/json_api.dart';
-
-void main() async {
-  final api = Api(version: "1.0");
-  final httpClient = Client();
-  final jsonApiClient = JsonApiClient(httpClient, documentFactory: DocumentFactory(api: api));
-}
-
-```
-
-
-# Server
-The server included in this package is still under development. It is not yet suitable for real production environment
-except maybe for really simple demo or testing cases.
-
-## URL Design
-The URL Design specifies the structure of the URLs used for specific targets. The JSON:API standard describes 4
-possible request targets:
-- Collections (parameterized by the resource type)
-- Individual resources (parameterized by the resource type and id)
-- Related resources and collections (parameterized by the resource type, resource id and the relation name)
-- Relationships (parameterized by the resource type, resource id and the relation name)
-
-The [UrlFactory] makes those 4 kinds of URLs by the given parameters. The [TargetMatcher] does the opposite,
-it determines the target of the given URL (if possible). Together they form the [UrlDesign].
-
-This package provides one built-in implementation of [UrlDesign] which is called [PathBasedUrlDesign].
-The [PathBasedUrlDesign] implements the [Recommended URL Design] allowing you to specify the a common prefix
-for all your JSON:API endpoints.
-
-
-[DocumentFactory]: https://pub.dev/documentation/json_api/latest/document_factory/DocumentFactory-class.html
-[Document.errors]: https://pub.dev/documentation/json_api/latest/document/Document/errors.html
-[JsonApiClient]: https://pub.dev/documentation/json_api/latest/client/JsonApiClient-class.html
-[PathBasedUrlDesign]: https://pub.dev/documentation/json_api/latest/url_design/PathBasedUrlDesign-class.html
-[PrimaryData.included]: https://pub.dev/documentation/json_api/latest/document/PrimaryData/included.html
-[Response]: https://pub.dev/documentation/json_api/latest/client/Response-class.html
-[Response.data]: https://pub.dev/documentation/json_api/latest/client/Response/data.html
-[Response.document]: https://pub.dev/documentation/json_api/latest/client/Response/document.html
-[Response.isSuccessful]: https://pub.dev/documentation/json_api/latest/client/Response/isSuccessful.html
-[Response.isFailed]: https://pub.dev/documentation/json_api/latest/client/Response/isFailed.html
-[Response.isAsync]: https://pub.dev/documentation/json_api/latest/client/Response/isAsync.html
-[Response.location]: https://pub.dev/documentation/json_api/latest/client/Response/location.html
-[Response.contentLocation]: https://pub.dev/documentation/json_api/latest/client/Response/contentLocation.html
-[Response.status]: https://pub.dev/documentation/json_api/latest/client/Response/status.html
-[Response.asyncDocument]: https://pub.dev/documentation/json_api/latest/client/Response/asyncDocument.html
-[Response.asyncData]: https://pub.dev/documentation/json_api/latest/client/Response/asyncData.html
-[TargetMatcher]: https://pub.dev/documentation/json_api/latest/url_design/TargetMatcher-class.html
-[UrlFactory]: https://pub.dev/documentation/json_api/latest/url_design/UrlFactory-class.html
-[UrlDesign]: https://pub.dev/documentation/json_api/latest/url_design/UrlDesign-class.html
-
-[Asynchronous Processing]: https://jsonapi.org/recommendations/#asynchronous-processing
-[Compound Documents]: https://jsonapi.org/format/#document-compound-documents
-[JSON:API Object]: https://jsonapi.org/format/#document-jsonapi-object
-[Recommended URL Design]: https://jsonapi.org/recommendations/#urls
+[JSON:API](http://jsonapi.org) is a specification for building APIs in JSON.
+
+This package consists of several libraries:
+- The [Client] to make requests to JSON:API servers
+- The [Server] which is still under development
+- The [Document] model for resources, relationships, identifiers, etc
+- The [Query] to build and parse the query parameters (pagination, sorting, etc)
+- The [URL Design] to build and match URLs for resources, collections, and relationships
+
+[Client]: https://pub.dev/documentation/json_api/latest/client/client-library.html
+[Server]: https://pub.dev/documentation/json_api/latest/server/server-library.html
+[Document]: https://pub.dev/documentation/json_api/latest/document/document-library.html
+[Query]: https://pub.dev/documentation/json_api/latest/query/query-library.html
+[URL Design]: https://pub.dev/documentation/json_api/latest/url_design/url_design-library.html

README.md

@@ -61,7 +61,7 @@ Future<HttpServer> createServer(InternetAddress addr, int port) async {
   final urlDesign = PathBasedUrlDesign(Uri.parse('http://localhost:$port'));
   final documentFactory =
       ServerDocumentFactory(urlDesign, pagination: pagination);
-  final jsonApiServer = Server(urlDesign, controller, documentFactory);
+  final jsonApiServer = JsonApiServer(urlDesign, controller, documentFactory);
 
   httpServer.forEach(jsonApiServer.serve);
   return httpServer;

example/cars_server.dart

@@ -10,48 +10,46 @@ import 'job_queue.dart';
 class CarsController implements Controller {
   final Map<String, DAO> _dao;
 
-  final Pagination _pagination;
+  final PaginationStrategy _pagination;
 
   CarsController(this._dao, this._pagination);
 
   @override
-  Response fetchCollection(String type, Query query) {
+  Response fetchCollection(String type, Uri uri) {
+    final page = Page.fromUri(uri);
     final dao = _getDaoOrThrow(type);
-    final collection = dao.fetchCollection(
-        _pagination.limit(query.page), _pagination.offset(query.page));
+    final collection =
+        dao.fetchCollection(_pagination.limit(page), _pagination.offset(page));
     return CollectionResponse(collection.elements.map(dao.toResource),
-        included: const [], total: collection.totalCount);
+        total: collection.totalCount);
   }
 
   @override
-  Response fetchRelated(
-      String type, String id, String relationship, Query query) {
+  Response fetchRelated(String type, String id, String relationship, Uri uri) {
     final res = _fetchResourceOrThrow(type, id);
-
+    final page = Page.fromUri(uri);
     if (res.toOne.containsKey(relationship)) {
       final id = res.toOne[relationship];
       final resource = _dao[id.type].fetchByIdAsResource(id.id);
       return RelatedResourceResponse(resource);
     }
-
     if (res.toMany.containsKey(relationship)) {
       final relationships = res.toMany[relationship];
       final resources = relationships
-          .skip(_pagination.offset(query.page))
-          .take(_pagination.limit(query.page))
+          .skip(_pagination.offset(page))
+          .take(_pagination.limit(page))
           .map((id) => _dao[id.type].fetchByIdAsResource(id.id));
-      return RelatedCollectionResponse(resources,
-          total: relationships.length, included: const []);
+      return RelatedCollectionResponse(resources, total: relationships.length);
     }
     return ErrorResponse.notFound(
         [JsonApiError(detail: 'Relationship not found')]);
   }
 
   @override
-  Response fetchResource(String type, String id, Query query) {
+  Response fetchResource(String type, String id, Uri uri) {
     final dao = _getDaoOrThrow(type);
-
     final obj = dao.fetchById(id);
+    final include = Include.fromUri(uri);
 
     if (obj == null) {
       return ErrorResponse.notFound(
@@ -64,16 +62,18 @@ class CarsController implements Controller {
     final fetchById = (Identifier _) => _dao[_.type].fetchByIdAsResource(_.id);
 
     final res = dao.toResource(obj);
-    final children = res.toOne.values
-        .map(fetchById)
-        .followedBy(res.toMany.values.expand((_) => _.map(fetchById)));
 
-    return ResourceResponse(res, included: children);
+    var filter = _filter(res.toMany, include.contains);
+    var followedBy = _filter(res.toOne, include.contains)
+        .values
+        .map(fetchById)
+        .followedBy(filter.values.expand((_) => _.map(fetchById)));
+    return ResourceResponse(res, included: followedBy);
   }
 
   @override
   Response fetchRelationship(
-      String type, String id, String relationship, Query query) {
+      String type, String id, String relationship, Uri uri) {
     final res = _fetchResourceOrThrow(type, id);
 
     if (res.toOne.containsKey(relationship)) {
@@ -203,4 +203,7 @@ class CarsController implements Controller {
     }
     return resource;
   }
+
+  Map<T, R> _filter<T, R>(Map<T, R> map, bool f(T t)) =>
+      {...map}..removeWhere((k, _) => !f(k));
 }

example/cars_server/controller.dart

@@ -1,4 +1,4 @@
-import 'package:json_api/json_api.dart';
+import 'package:json_api/document.dart';
 
 import 'collection.dart';
 import 'job_queue.dart';

example/cars_server/dao.dart

@@ -1,6 +1,6 @@
 import 'dart:async';
 
-import 'package:json_api/json_api.dart';
+import 'package:json_api/document.dart';
 import 'package:uuid/uuid.dart';
 
 class Job {

example/cars_server/job_queue.dart

@@ -1,22 +1,15 @@
 import 'package:http/http.dart';
-import 'package:json_api/json_api.dart';
+import 'package:json_api/client.dart';
 
+/// Start the `cars_server.dart` first!
 void main() async {
   final httpClient = Client();
   final jsonApiClient = JsonApiClient(httpClient);
-  final companiesUri = Uri.parse('http://localhost:8080/companies');
-  final response = await jsonApiClient.fetchCollection(companiesUri);
-  httpClient.close();
-  print('Status: ${response.status}');
-  print('Headers: ${response.headers}');
-
-  final resource = response.data.unwrap().first;
-
+  final url = Uri.parse('http://localhost:8080/companies/2');
+  final response = await jsonApiClient.fetchCollection(url);
+  httpClient.close(); // Don't forget to close the http client
   print('The collection page size is ${response.data.collection.length}');
-  print('The first element is ${resource}');
-  print('Attributes:');
-  resource.attributes.forEach((k, v) => print('$k=$v'));
-  print('Relationships:');
-  resource.toOne.forEach((k, v) => print('$k=$v'));
-  resource.toMany.forEach((k, v) => print('$k=$v'));
+  final resource = response.data.unwrap().first;
+  print('The last element is ${resource}');
+  resource.attributes.forEach((k, v) => print('Attribute $k is $v'));
 }

example/fetch_collection.dart

@@ -1,4 +1,6 @@
-export 'package:json_api/src/client/client.dart';
+library client;
+
 export 'package:json_api/src/client/client_document_factory.dart';
+export 'package:json_api/src/client/json_api_client.dart';
 export 'package:json_api/src/client/response.dart';
 export 'package:json_api/src/client/status_code.dart';