json_api_document 0.3.2

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

JSON API Document model and parser

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.2 - 2018-11-05

Changes #

  • 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.3.2

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_document/json_api_document.dart';
  
Version Uploaded Documentation Archive
1.0.2 Apr 13, 2019 Go to the documentation of json_api_document 1.0.2 Download json_api_document 1.0.2 archive
1.0.1 Apr 3, 2019 Go to the documentation of json_api_document 1.0.1 Download json_api_document 1.0.1 archive
1.0.0+2 Apr 1, 2019 Go to the documentation of json_api_document 1.0.0+2 Download json_api_document 1.0.0+2 archive
1.0.0+1 Mar 30, 2019 Go to the documentation of json_api_document 1.0.0+1 Download json_api_document 1.0.0+1 archive
1.0.0 Mar 29, 2019 Go to the documentation of json_api_document 1.0.0 Download json_api_document 1.0.0 archive
0.6.0+1 Mar 28, 2019 Go to the documentation of json_api_document 0.6.0+1 Download json_api_document 0.6.0+1 archive
0.6.0 Mar 26, 2019 Go to the documentation of json_api_document 0.6.0 Download json_api_document 0.6.0 archive
0.5.0 Mar 25, 2019 Go to the documentation of json_api_document 0.5.0 Download json_api_document 0.5.0 archive
0.4.0 Mar 25, 2019 Go to the documentation of json_api_document 0.4.0 Download json_api_document 0.4.0 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

All 38 versions...

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

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

  • Dart: 2.3.1
  • pana: 0.12.16

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/relationship.dart. (-1 points)

Analysis of lib/src/relationship.dart reported 2 hints:

line 15 col 17: Don't type annotate initializing formals.

line 15 col 33: Don't type annotate initializing formals.

Fix lib/src/data_document.dart. (-0.50 points)

Analysis of lib/src/data_document.dart reported 1 hint:

line 119 col 26: Don't type annotate initializing formals.

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

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

line 60 col 9: Use isNotEmpty instead of length

Fix additional 4 files with analysis or formatting issues. (-2 points)

Additional issues in the following files:

  • lib/src/identifier_data.dart (1 hint)
  • lib/src/naming.dart (1 hint)
  • lib/src/resource.dart (1 hint)
  • lib/src/resource_data.dart (1 hint)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
Dev dependencies
json_matcher >=0.2.2
pubspec_version ^0.1.0
test 1.3.0