json_api 2.0.0-dev.1

JSON:API Client for Flutter, Web and VM. Supports JSON:API v1.0 (http://jsonapi.org)

Other JSON:API packages: Document | Server

---

JSON:API Client

JSON:API is a specification for building APIs in JSON. This package implements the Client.

Features

• Fetching single resources, resource collections, related resources
• Fetching/updating relationships
• Creating/updating/deleting resources
• Collection pagination
• Compound documents (included resources)
• 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_client.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'));
}

The Response object

The Client always returns a Response object which indicates either a successful, failed, or async (neither failed nor successful yet, see here) operation. You can determine which one you have by reading these properties:

• isSuccessful
• isFailed
• isAsync

The Response also contains HTTP status and a map of HTTP headers. Two headers used by JSON:API can be accessed directly for your convenience:

• location - the Location: header used in creation requests
• contentLocation - the Content-Location: header used for asynchronous processing

The Response Document

The most important part of the Response is the document property which contains the JSON:API document sent by the server (if any). If the document has Primary Data, you can use data shortcut to access it directly. Like the Document, the Response is generalized by the expected Primary Data which depends of the operation. The Document and the rest of the JSON:API object model are parts of json_api_document which is a separate package. Refer to that package for complete API documentation. This README only gives a brief overview.

Successful responses

Most of the times when the response is successful, you can read the data property directly. It will be either a primary resource , primary resource collection, or a relationship: to-one or to-many. The collection-like data may also contain pagination links.

Included resources

If you requested related resources to be included in the response (see Compound Documents) and the server fulfilled your request, the included property will contain them.

Errors

For unsuccessful operations the data property will be null. If the server decided to include the error details in the response, those can be found in the 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, the document and the data properties of the Response will be null. Instead, the response document will be placed to asyncDocument (and asyncData). Also in this case the 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.

Further reading

For more usage examples refer to the functional tests.