json_api_document 0.4.0-dev.2

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

JSON:API v1.0 implementation in Dart2. Document builder. Document parser. HTTP client.

The goal of this library is to provide a transparent way to build and parse JSON API Documents.

These are the key values of the library:

  • Immutability. Produced documents are immutable value objects.
  • Native JSON support. Use the built-in json.encode() to convert to a JSON string.
  • Strict standard compliance. All JSON API Documents are guaranteed to follow JSON API v1.0.

Building JSON API Document #

To get a sense of what the library API looks like, take a look at the example:

import 'dart:convert';

import 'package:json_api_document/json_api_document.dart';

/// The following function produces the example document
/// from the first page of http://jsonapi.org/.
Document makeJsonApiResponse() {
  final dan = Resource('people', '9',
      attributes: {
        'first-name': 'Dan',
        'last-name': 'Gebhardt',
        'twitter': 'dgeb'
      },
      self: Link('http://example.com/people/9'));

  final personIdentifier = Identifier('people', '2');

  final firstComment = Resource('comments', '5',
      attributes: {'body': 'First!'},
      relationships: {'author': ToOne(personIdentifier)},
      self: Link('http://example.com/comments/5'));

  final secondComment = Resource('comments', '12',
      attributes: {'body': 'I like XML better'},
      relationships: {'author': ToOne(Identifier.of(dan))},
      self: Link('http://example.com/comments/12'));

  final article = Resource(
    'articles',
    '1',
    self: Link('http://example.com/articles/1'),
    attributes: {'title': 'JSON API paints my bikeshed!'},
    relationships: {
      'author': ToOne(
        Identifier.of(dan),
        self: Link('http://example.com/articles/1/relationships/author'),
        related: Link('http://example.com/articles/1/author'),
      ),
      'comments': ToMany(
          [Identifier.of(firstComment), Identifier.of(secondComment)],
          self: Link('http://example.com/articles/1/relationships/comments'),
          related: Link('http://example.com/articles/1/comments'))
    },
  );

  return DataDocument.fromResourceList([article],
      self: Link('http://example.com/articles'),
      next: Link('http://example.com/articles?page[offset]=2'),
      last: Link('http://example.com/articles?page[offset]=10'),
      included: [dan, firstComment, secondComment]);
}

/// Print the JSON representation of the response to stdout
void main() {
  final response = makeJsonApiResponse();
  print(json.encode(response));
}

This code will produce the following output:

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {"title": "JSON API paints my bikeshed!"},
      "relationships": {
        "author": {
          "links": {
            "self":
                "http://example.com/articles/1/relationships/author",
            "related": "http://example.com/articles/1/author"
          },
          "data": {"type": "people", "id": "9"}
        },
        "comments": {
          "links": {
            "self":
                "http://example.com/articles/1/relationships/comments",
            "related": "http://example.com/articles/1/comments"
          },
          "data": [
            {"type": "comments", "id": "5"},
            {"type": "comments", "id": "12"}
          ]
        }
      },
      "links": {"self": "http://example.com/articles/1"}
    }
  ],
  "included": [
    {
      "type": "people",
      "id": "9",
      "attributes": {
        "first-name": "Dan",
        "last-name": "Gebhardt",
        "twitter": "dgeb"
      },
      "links": {"self": "http://example.com/people/9"}
    },
    {
      "type": "comments",
      "id": "5",
      "attributes": {"body": "First!"},
      "relationships": {
        "author": {
          "data": {"type": "people", "id": "2"}
        }
      },
      "links": {"self": "http://example.com/comments/5"}
    },
    {
      "type": "comments",
      "id": "12",
      "attributes": {"body": "I like XML better"},
      "relationships": {
        "author": {
          "data": {"type": "people", "id": "9"}
        }
      },
      "links": {"self": "http://example.com/comments/12"}
    }
  ]
}

Parsing JSON API Document #

This example reads the JSON API from stdin and prints some details about it:

import 'dart:convert';
import 'dart:io';

import 'package:json_api_document/json_api_document.dart';

void main() async {
  final jsonString = await stdin.transform(Utf8Decoder()).join();
  final jsonObject = json.decode(jsonString);
  final doc = Document.fromJson(jsonObject);
  print('This is ${doc.runtimeType}');
  if (doc is DataDocument) {
    print('The primary data is ${doc.data.runtimeType} ' +
        'with ${doc.data.resources.length} resource(s).');
    print('The document contains ${doc.included.length} included resource(s).');
  }
}

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 #

[0.3.5] - 2019-01-05

Added #

  • PrimaryData and its subclasses are now exposed

0.3.4 - 2019-01-05

Fixed #

  • Document.fromJson does not recognize null resource id

0.3.3 - 2019-01-05

Added #

  • Document.mediaType constant

0.3.2 - 2018-11-05

Changed #

  • Minor documentation improvements

0.3.0 - 2018-11-05

Added #

  • Parsing capabilities.
  • A few accessors to Meta, Attributes, Relationships

Removed #

  • Link.isObject
  • Link.meta

0.2.2 - 2018-10-09

Added #

  • Enforce naming rules on relationships
  • Included resources are checked for duplicates
  • LinkObject
  • Pagination links for data collection documents
  • Resource fields uniqueness enforcement

0.2.1 - 2018-10-05

Added #

  • Compound documents
  • Meta property to Identifier
  • Prohibit creating empty Api objects

0.2.0 - 2018-10-03 #

Added #

  • Initial usable implementation

example/readme.md

Building stuff #

build.dart builds a new JSON API Document and prints its JSON representation.

Run

dart example/build.dart

to produce a sample JSON API Document. For your convenience, document.json already contains the pretty-printed version of this document.

Parsing stuff #

parse.dart parses any JSON API document from the standard input.

Run

dart example/parse.dart < example/document.json

to parse the example document. This will produce the following output:

This is DataDocument
The primary data is ResourceListData with 1 resource(s).
The document contains 3 included resource(s).

Use this package as a library

1. Depend on it

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


dependencies:
  json_api_document: ^0.4.0-dev.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages 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_document/json_api_document.dart';
  
Version Uploaded Documentation Archive
0.3.10 Jan 21, 2019 Go to the documentation of json_api_document 0.3.10 Download json_api_document 0.3.10 archive
0.3.9 Jan 9, 2019 Go to the documentation of json_api_document 0.3.9 Download json_api_document 0.3.9 archive
0.3.8 Jan 8, 2019 Go to the documentation of json_api_document 0.3.8 Download json_api_document 0.3.8 archive
0.3.7 Jan 8, 2019 Go to the documentation of json_api_document 0.3.7 Download json_api_document 0.3.7 archive
0.3.6 Jan 8, 2019 Go to the documentation of json_api_document 0.3.6 Download json_api_document 0.3.6 archive
0.3.5 Jan 5, 2019 Go to the documentation of json_api_document 0.3.5 Download json_api_document 0.3.5 archive
0.3.4 Jan 5, 2019 Go to the documentation of json_api_document 0.3.4 Download json_api_document 0.3.4 archive
0.3.3 Jan 4, 2019 Go to the documentation of json_api_document 0.3.3 Download json_api_document 0.3.3 archive
0.3.2 Nov 6, 2018 Go to the documentation of json_api_document 0.3.2 Download json_api_document 0.3.2 archive
0.3.1 Nov 6, 2018 Go to the documentation of json_api_document 0.3.1 Download json_api_document 0.3.1 archive

All 27 versions...

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

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

  • Dart: 2.1.0
  • pana: 0.12.13

Platforms

Detected platforms: Flutter, web, other

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

Health suggestions

Fix lib/src/document/error_object.dart. (-0.50 points)

Analysis of lib/src/document/error_object.dart reported 1 hint:

line 60 col 9: Use isNotEmpty instead of length

Maintenance suggestions

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
http ^0.12.0 0.12.0+1
Transitive dependencies
async 2.0.8
charcode 1.1.2
collection 1.14.11
http_parser 3.1.3
meta 1.1.7
path 1.6.2
source_span 1.5.4
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
Dev dependencies
json_matcher >=0.2.2
pubspec_version ^0.1.0
test 1.3.0