v0.0.1

Author: f3ath

CHANGELOG.md

@@ -3,3 +3,11 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## 0.0.1 - 2019-01-08
+### Added
+- Initial client implementation
+
+[Unreleased]: https://github.com/f3ath/json-api-dart/compare/0.0.1...HEAD

README.md

@@ -1,3 +1,3 @@
 # [JSON:API](http://jsonapi.org) v1.0 HTTP Client
 
-This is a work-in-progress. Feel free to join.
+This is a super simple implementation of a

example/example.dart

@@ -3,7 +3,7 @@ import 'package:json_api_document/json_api_document.dart';
 
 /// This is a simple example of JsonApiClient.
 ///
-/// Do not forget to start server.dart first!
+/// Don't forget to start server.dart first!
 void main() async {
   final client = JsonApiClient(baseUrl: 'http://localhost:8888');
   final response = await client.fetchResource('/example');

lib/src/json_api_client.dart

@@ -24,26 +24,26 @@ class JsonApiClient {
   final api = Api('1.0');
 
   /// Fetches a [Document] containing resource(s) from the given [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#fetching-resources
   Future<Response> fetchResource(String url,
           {Map<String, String> headers = const {}}) async =>
       Response(await _exec((_) => _.get(_url(url), headers: _headers(headers))),
           preferResource: true);
 
   /// Fetches a [Document] containing identifier(s) from the given [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#fetching-relationships
   Future<Response> fetchRelationship(String url,
           {Map<String, String> headers = const {}}) async =>
       Response(
           await _exec((_) => _.get(_url(url), headers: _headers(headers))));
 
   /// Creates a new [resource] sending a POST request to the [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#crud-creating
   Future<Response> createResource(String url, Resource resource,
           {Map<String, String> headers = const {}}) async =>
@@ -54,17 +54,17 @@ class JsonApiClient {
           preferResource: true);
 
   /// Deletes the resource sending a DELETE request to the [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#crud-deleting
   Future<Response> deleteResource(String url,
           {Map<String, String> headers = const {}}) async =>
       Response(
           await _exec((_) => _.delete(_url(url), headers: _headers(headers))));
 
   /// Updates the [resource] sending a PATCH request to the [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#crud-updating
   Future<Response> updateResource(String url, Resource resource,
           {Map<String, String> headers = const {}}) async =>
@@ -76,8 +76,8 @@ class JsonApiClient {
 
   /// Creates or updates a to-one relationship sending a corresponding
   /// [identifier] via PATCH request to the [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#crud-updating-to-one-relationships
   Future<Response> setToOne(String url, Identifier identifier,
           {Map<String, String> headers = const {}}) async =>
@@ -87,27 +87,58 @@ class JsonApiClient {
 
   /// Removes a to-one relationship sending PATCH request with "null" data
   /// to the [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#crud-updating-to-one-relationships
   Future<Response> deleteToOne(String url,
           {Map<String, String> headers = const {}}) async =>
       Response(await _exec((_) => _.patch(_url(url),
           body: json.encode(DataDocument.fromNull(api: api)),
           headers: _headers(headers, withContentType: true))));
 
-  /// Updates a to-many relationship sending the
+  /// Updates (replaces!) a to-many relationship sending the
   /// [identifiers] via PATCH request to the [url].
-  /// Pass a [Map] of [headers] to add extra headers to the request.
   ///
+  /// This call **completely replaces** the set of relationships. E.g. when given
+  /// an empty array, it will remove all relationships.
+  /// Pass a [Map] of [headers] to add extra headers to the request.
   /// More details: https://jsonapi.org/format/#crud-updating-to-many-relationships
-  setToMany(String url, List<Identifier> identifiers,
+  Future<Response> setToMany(String url, List<Identifier> identifiers,
           {Map<String, String> headers = const {}}) async =>
       Response(await _exec((_) => _.patch(_url(url),
           body: json
               .encode(DataDocument.fromIdentifierList(identifiers, api: api)),
           headers: _headers(headers, withContentType: true))));
 
+  /// Adds the [identifiers] to the to-many relationship via POST request to the [url].
+  ///
+  /// The existing members of the relationships will be kept.
+  /// Pass a [Map] of [headers] to add extra headers to the request.
+  /// More details: https://jsonapi.org/format/#crud-updating-to-many-relationships
+  Future<Response> addToMany(String url, List<Identifier> identifiers,
+          {Map<String, String> headers = const {}}) async =>
+      Response(await _exec((_) => _.post(_url(url),
+          body: json
+              .encode(DataDocument.fromIdentifierList(identifiers, api: api)),
+          headers: _headers(headers, withContentType: true))));
+
+  /// Deletes the [identifiers] from the to-many relationship via DELETE request to the [url].
+  ///
+  /// The other existing members of the relationships will be kept.
+  /// Pass a [Map] of [headers] to add extra headers to the request.
+  /// More details: https://jsonapi.org/format/#crud-updating-to-many-relationships
+  Future<Response> deleteToMany(String url, List<Identifier> identifiers,
+      {Map<String, String> headers = const {}}) async {
+    // http.Client at version 0.12.0 does not support delete() with a body
+    // So we will have to make the Request object
+    final request = http.Request('DELETE', Uri.parse(_url(url)));
+    request.body =
+        json.encode(DataDocument.fromIdentifierList(identifiers, api: api));
+    request.headers.addAll(_headers(headers, withContentType: true));
+    return Response(await _exec(
+        (_) async => http.Response.fromStream(await _.send(request))));
+  }
+
   String _url(String url) => '${baseUrl}${url}';
 
   Map<String, String> _headers(Map<String, String> headers,

lib/src/response.dart

@@ -4,10 +4,19 @@ import 'package:http/http.dart' as http;
 import 'package:json_api/src/exceptions.dart';
 import 'package:json_api_document/json_api_document.dart';
 
-/// A result of a fetch() request.
+/// A response from a JSON:API server.
+///
+/// The client wraps the responses from JSON:API server in a [Response] class.
+/// This class contains the decoded JSON:API document (if any) and other details
+/// such as HTTP status code and HTTP headers.
 class Response {
+  /// JSON:API document returned by the server.
+  ///
+  /// May be null if the body is empty.
   final Document document;
+  /// HTTP status code
   final int status;
+  /// HTTP headers
   final Map<String, String> headers;
 
   Response(http.Response r, {bool preferResource = false})
@@ -24,5 +33,9 @@ class Response {
     throw InvalidContentTypeException(headers[contentType]);
   }
 
+  /// The "Location:" headers (if provided).
+  ///
+  /// This header comes with "201 Created" responses".
+  /// More details: https://jsonapi.org/format/#crud-creating-responses-201
   String get location => headers['location'];
 }

pubspec.yaml

@@ -2,7 +2,7 @@ author: "Alexey Karapetov <karapetov@gmail.com>"
 description: "JSON:API v1.0 (http://jsonapi.org) HTTP Client for Flutter, Server and Browsers"
 homepage: "https://github.com/f3ath/json-api-dart"
 name: "json_api"
-version: "0.0.1-dev3"
+version: "0.0.1-dev5"
 dependencies:
   http: "^0.12.0"
   json_api_document: "^0.3.9"

test/json_api_client_test.dart

@@ -278,8 +278,8 @@ void main() {
         rq.response.close();
       });
 
-      final result = await client
-          .setToOne('/update', identifier, headers: {'foo': 'bar'});
+      final result =
+          await client.setToOne('/update', identifier, headers: {'foo': 'bar'});
 
       expect(result.status, HttpStatus.ok);
     }, tags: ['vm-only']);
@@ -296,7 +296,6 @@ void main() {
   ///
 
   group('deleteToOne()', () {
-
     test('200', () async {
       server.listen((rq) async {
         expect(rq.method, 'PATCH');
@@ -312,8 +311,8 @@ void main() {
         rq.response.close();
       });
 
-      final result = await client
-          .deleteToOne('/update', headers: {'foo': 'bar'});
+      final result =
+          await client.deleteToOne('/update', headers: {'foo': 'bar'});
 
       expect(result.status, HttpStatus.ok);
     }, tags: ['vm-only']);
@@ -329,7 +328,7 @@ void main() {
 
   ///
 
-  group('setToMany()', () {
+  group('replaceToMany()', () {
     final apple1 = Identifier('apples', '1');
     final apple2 = Identifier('apples', '2');
 
@@ -367,5 +366,83 @@ void main() {
     });
   }, tags: ['vm-only']);
 
+  ///
+
+  group('addToMany()', () {
+    final apple1 = Identifier('apples', '1');
+    final apple2 = Identifier('apples', '2');
+
+    test('200', () async {
+      server.listen((rq) async {
+        expect(rq.method, 'POST');
+        expect(rq.headers['foo'], ['bar']);
+        expect(rq.uri.path, '/add');
+        expect(rq.headers.host, 'localhost');
+        expect(rq.headers.port, 4041);
+        final doc = Document.fromJson(json.decode(await utf8.decodeStream(rq)));
+        expect(doc, TypeMatcher<DataDocument>());
+        expect((doc as DataDocument).data, TypeMatcher<IdentifierListData>());
+        expect((doc as DataDocument).data.identifies(Resource('apples', '1')),
+            true);
+        expect((doc as DataDocument).data.identifies(Resource('apples', '2')),
+            true);
+
+        rq.response.headers.contentType = ContentType.parse(Document.mediaType);
+        rq.response.close();
+      });
+
+      final result = await client
+          .addToMany('/add', [apple1, apple2], headers: {'foo': 'bar'});
 
+      expect(result.status, HttpStatus.ok);
+    }, tags: ['vm-only']);
+
+    test('invalid Content-Type', () async {
+      server.listen((rq) {
+        rq.response.close();
+      });
+      expect(() async => await client.addToMany('/add', [apple1, apple2]),
+          throwsA(TypeMatcher<InvalidContentTypeException>()));
+    });
+  }, tags: ['vm-only']);
+
+  ///
+
+  group('deleteToMany()', () {
+    final apple1 = Identifier('apples', '1');
+    final apple2 = Identifier('apples', '2');
+
+    test('200', () async {
+      server.listen((rq) async {
+        expect(rq.method, 'DELETE');
+        expect(rq.headers['foo'], ['bar']);
+        expect(rq.uri.path, '/add');
+        expect(rq.headers.host, 'localhost');
+        expect(rq.headers.port, 4041);
+        final doc = Document.fromJson(json.decode(await utf8.decodeStream(rq)));
+        expect(doc, TypeMatcher<DataDocument>());
+        expect((doc as DataDocument).data, TypeMatcher<IdentifierListData>());
+        expect((doc as DataDocument).data.identifies(Resource('apples', '1')),
+            true);
+        expect((doc as DataDocument).data.identifies(Resource('apples', '2')),
+            true);
+
+        rq.response.headers.contentType = ContentType.parse(Document.mediaType);
+        rq.response.close();
+      });
+
+      final result = await client
+          .deleteToMany('/add', [apple1, apple2], headers: {'foo': 'bar'});
+
+      expect(result.status, HttpStatus.ok);
+    }, tags: ['vm-only']);
+
+    test('invalid Content-Type', () async {
+      server.listen((rq) {
+        rq.response.close();
+      });
+      expect(() async => await client.deleteToMany('/add', [apple1, apple2]),
+          throwsA(TypeMatcher<InvalidContentTypeException>()));
+    });
+  }, tags: ['vm-only']);
 }