JSON API Spec

Based on the official v1.0 specification, all the features should be implemented. If something is missing or not behaving correctly, feel free to open an issue.

Limitations

v4 limitations

• attributes and relationships shouldn't use same properties
• Possible collisions if attributes or relationships contain properties already used for internal Record needs

v3 limitations

Version 3 has the same limitations as version 4 and some additional:

The following limitations are addressed in the v4:

• attributes shouldn't contain a type or id if they're different from the record type or id
• If a local record is referenced in another record, then persisted on the server (id changed), the reference will be lost

Content Negotiation

Client Responsibilities

• The lib is already setting the required headers, but you can also extend/override them if needed

Server Responsibilities

• If the server returns any HTTP status 400 or greater (including 406 and 415 mentioned in the spec), the request promise will reject with a Response object that has its error property set (message & HTTP status)

Document Structure

Top Level

• The lib supports data, errors, meta, links, included, and jsonapi properties:
  • data, error and jsonapi are exsposed in the Response object
  • included is consumed by the sync method
  • meta and links values are available on the Record with getMeta, getLinks, fetchLink, getRelationshipLinks, fetchRelationshipLink and a computed meta property for relationships (record[relationshipName + 'Meta']

Resource Objects

• The lib expects id and type properties, and they're available on the Record instance
• If the resource has attributes, they will be available as regular properties on the Record instance
• If the resource has relationships
  • links will be available using the getRelationshipLinks method on the record
    • Use fetchRelationshipLink to fetch the link
  • data will be used to build the references between models
    • If the store already contains the referenced model or includes contains the model it will be available right away on the record: record[relName]. Also, the id is available on record[relName + 'Id']
    • If the model is "unknown", the id will be available on record[relName + 'Id']
  • meta is available on record[relName + 'Meta']
• If the resource has links or meta, they will be available with the getLinks and getMeta methods on the record
  • Use fetchLink to fetch the link

Resource Identifier Objects

• The lib expects id and type
• meta is available on record[relName + 'Meta']

Compound Objects

• The lib supports included property
• The lib will add included resources as references to the data resources
• The included resources are treated as regular records, just like the data resources, with same features and limitations

Meta Information

• The meta property will be available directly on the Response object

Links

• The links property is supported, and exposes all links directly on the Response object
• They are also available in raw form as a links property on the Response object
• response[linkName] is a Promise that will resolve to a Response with either the data or error property set
  • The link is lazily evaluated, so the request won't be made until you access the property
  • The link can be a string with an URL

JSON API Object

• The jsonapi property is available on the Response object instance

Member Names

• All member names are treated as strings, therefore adhere to the specification
• If a name is not a valid variable name, e.g. "first-name", you can access it as record['first-name']

Fetching Data

Fetching Resources

• Fetch top-level links
• Fetch resource-level links with fetchLink
• Fetch related link from relationship-level links with fetchRelationshipLink

Fetching Relationships

• Fetch relationship-level links with fetchRelationshipLink

Inclusion of Related Resources

• Supported by providing a include property in the request options (IRequestOptions)

Sparse Fieldsets

• Supported by providing a fields property in the request options (IRequestOptions)

Sorting

• Supported by providing a sort property in the request options (IRequestOptions)

Pagination

• The lib supports top-level links
• The lib allows access to raw links in the links property of the Response object instance
• The lib allows pagination with links, e.g. response.next will return a Promise that will resolve to a Response object with either the data or error property set
  • The link is lazily evaluated, so the request won't be made until you access the property

Filtering

• Supported by providing a filter property in the request options (IRequestOptions)

Creating, Updating and Deleting Resources

Creating Resources

• Creating resources is supported using the save method if the record was created on the client
• Client-Generated IDs are supported
  • set useAutogeneratedIds to true
  • override autoIdFunction so it returns a valid UUID

Updating Resources

• Updating resources is supported using the save method if the record was not created on the client

Updating Relationships

• Direct update of relationships is supported with the saveRelationship method
• Tip: If you want to add a new relationship, use assignRef

Deleting Resources

• The resource can be deleted with the remove method on the record

Query Parameters

• All current communication with the server is using the required naming method

Errors

Processing Errors

• The lib will process all HTTP status 400+ as errors

Error Objects

• The error objects will be available in the Response object under the error property (without any modification)