json_api 1.0.1

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 83

Other JSON:API packages: Document | Server


JSON:API Client #

JSON:API is a specification for building APIs in JSON. This library implements a Client (VM, Flutter, Web).

Features #

  • Fetching single resources, resource collections, related resources
  • Fetching/updating relationships
  • Creating/updating/deleting resources
  • Collection pagination
  • Compound documents
  • Asynchronous processing

Usage #

Creating a client instance #

JSON:API Client uses the Dart's native HttpClient. Depending on the platform, you may want to use either the one which comes from dart:io or the BrowserClient.

In the VM/Flutter you don't need to provide any dependencies:

import 'package:json_api/json_api.dart';

final client = JsonApiClient();

In a browser use the BrowserClient:

import 'package:json_api/json_api.dart';
import 'package:http/browser_json_api.dart';

final client = JsonApiClient(factory: () => BrowserClient());

Making requests #

The client provides a set of methods to manipulate resources and relationships.

  • Fetching
    • fetchCollection - resource collection, either primary or related
    • fetchResource - a single resource, either primary or related
    • fetchRelationship - a generic relationship (either to-one, to-many or even incomplete)
    • fetchToOne - a to-one relationship
    • fetchToMany - a to-many relationship
  • Manipulating resources
    • createResource - creates a new primary resource
    • updateResource - updates the existing resource by its type and id
    • deleteResource - deletes the existing resource
  • Manipulating relationships
    • replaceToOne - replaces the existing to-one relationship with a new resource identifier
    • deleteToOne - deletes the existing to-one relationship by setting the resource identifier to null
    • replaceToMany - replaces the existing to-many relationship with the given set of resource identifiers
    • addToMany - 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 Response object bearing the HTTP response status and headers and the JSON:API document with the primary data according to the type of the request.

Here's a collection fetching example:

import 'package:json_api/json_api.dart';

void main() async {
  final client = JsonApiClient();
  final companiesUri = Uri.parse('http://localhost:8080/companies');
  final response = await client.fetchCollection(companiesUri);

  print('Status: ${response.status}');
  print('Headers: ${response.headers}');

  print('The collection page size is ${response.data.collection.length}');

  final resource = response.data.collection.first.toResource();
  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'));
}

For more usage examples refer to the functional tests.

Changelog #

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased #

1.0.1 - 2019-04-05

Changed #

  • Bump the dependencies' versions

1.0.0 - 2019-03-20

Changed #

  • JSON:API Server moved out

0.6.0 - 2019-03-25

Changed #

  • JSON:API Document moved out
  • Renamed client.removeToOne(...) to client.deleteToOne(...)

0.5.0 - 2019-03-21

Changed #

  • More BC-breaking changes in the Server

Fixed #

  • Location headers were incorrectly generated by Server

Added #

  • Related collection pagination
  • Async operations support

0.4.0 - 2019-03-17

Changed #

  • Parsing logic moved out
  • Some other BC-breaking changes in the Document
  • Huge changes in the Server

Added #

  • Compound documents support in Client (Server-side support is still very limited)

Fixed #

  • Server was not setting links for resources and relationships

0.3.0 - 2019-03-16

Changed #

  • Huge BC-breaking refactoring in the Document model which propagated everywhere

Added #

  • Resource attributes update
  • Resource relationships update

0.2.0 - 2019-03-01

Added #

  • Improved ResourceController error handling
  • Resource creation
  • Resource deletion

0.1.0 - 2019-02-27 #

Added #

  • Client: fetch resources, collections, related resources and relationships

example/README.md

JSON:API examples #

Cars Server #

This is a simple JSON:API server which is used in the tests. It provides an API to a collection to car companies and models. You can run it locally to play around.

Fetch example #

With the server running, call

dart example/fetch_collection.dart

This will make a fetchCollection() call and print the response.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  json_api: ^1.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:json_api/json_api.dart';
  
Version Uploaded Documentation Archive
1.0.1 Apr 5, 2019 Go to the documentation of json_api 1.0.1 Download json_api 1.0.1 archive
1.0.0 Mar 30, 2019 Go to the documentation of json_api 1.0.0 Download json_api 1.0.0 archive
0.6.0+1 Mar 28, 2019 Go to the documentation of json_api 0.6.0+1 Download json_api 0.6.0+1 archive
0.6.0 Mar 26, 2019 Go to the documentation of json_api 0.6.0 Download json_api 0.6.0 archive
0.5.0 Mar 21, 2019 Go to the documentation of json_api 0.5.0 Download json_api 0.5.0 archive
0.4.0 Mar 18, 2019 Go to the documentation of json_api 0.4.0 Download json_api 0.4.0 archive
0.3.0 Mar 17, 2019 Go to the documentation of json_api 0.3.0 Download json_api 0.3.0 archive
0.2.0 Mar 1, 2019 Go to the documentation of json_api 0.2.0 Download json_api 0.2.0 archive
0.1.0 Feb 27, 2019 Go to the documentation of json_api 0.1.0 Download json_api 0.1.0 archive
0.0.1 Jan 9, 2019 Go to the documentation of json_api 0.0.1 Download json_api 0.0.1 archive

All 26 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
70
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
83
Learn more about scoring.

We analyzed this package on Jun 17, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.3.2
  • pana: 0.12.18

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:json_api/json_api.dart.

Maintenance issues and suggestions

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (1 direct: json_api_document).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
collection ^1.14.11 1.14.11
http ^0.12.0 0.12.0+2
json_api_document ^1.0.1 1.0.2 1.1.0-dev.2
Transitive dependencies
async 2.2.0
charcode 1.1.2
http_parser 3.1.3
meta 1.1.7
path 1.6.2
pedantic 1.7.0
source_span 1.5.5
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
Dev dependencies
json_api_server ^0.0.1
json_matcher ^0.2.3
stream_channel ^1.6.8
test ^1.6.1
uuid ^2.0.1