active_model_serializers/docs/jsonapi/schema.md

JSON API Requests

• Query Parameters Spec

Headers:

• Request: Accept: application/vnd.api+json
• Response: Content-Type: application/vnd.api+json

Fetching Data

A server MUST support fetching resource data for every URL provided as:

• a self link as part of the top-level links object
• a self link as part of a resource-level links object
• a related link as part of a relationship-level links object

Example supported requests

• Individual resource or collection
  • GET /articles
  • GET /articles/1
  • GET /articles/1/author
• Relationships
  • GET /articles/1/relationships/comments
  • GET /articles/1/relationships/author
• Optional: Inclusion of related resources ActiveModel::Serializer::Fieldset
  • GET /articles/1?include=comments
  • GET /articles/1?include=comments.author
  • GET /articles/1?include=author,comments.author
  • GET /articles/1/relationships/comments?include=comments.author
• Optional: Sparse Fieldsets ActiveModel::Serializer::Fieldset
  • GET /articles?include=author&fields[articles]=title,body&fields[people]=name
• Optional: Sorting
  • GET /people?sort=age
  • GET /people?sort=age,author.name
  • GET /articles?sort=-created,title
• Optional: Pagination
  • GET /articles?page[number]=3&page[size]=1
• Optional: Filtering
  • GET /comments?filter[post]=1
  • GET /comments?filter[post]=1,2
  • GET /comments?filter[post]=1,2

CRUD Actions

Asynchronous Processing

Bulk Operations Extension

JSON API Document Schema

JSON API object	JSON API properties	Required	ActiveModelSerializers representation
schema	oneOf (success, failure, info)
success	data, included, meta, links, jsonapi		ActiveModel::SerializableResource
success.meta	meta		ActiveModel::Serializer::Adapter::Base#meta
success.included	UniqueArray(resource)		ActiveModel::Serializer::Adapter::JsonApi#serializable_hash_for_collection
success.data	data
success.links	allOf (links, pagination)		ActiveModel::Serializer::Adapter::JsonApi#links_for
success.jsonapi	jsonapi
failure	errors, meta, jsonapi	errors
failure.errors	UniqueArray(error)		#1004
meta	Object
data	oneOf (resource, UniqueArray(resource))		ActiveModel::Serializer::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
resource	String(type), String(id), attributes, relationships, links, meta	type, id	ActiveModel::Serializer::Adapter::JsonApi#primary_data_for
links	Uri(self), Link(related)		#1028, #1246, #1282
link	oneOf (linkString, linkObject)
link.linkString	Uri
link.linkObject	Uri(href), meta	href
attributes	patternProperties( `"^(?!relationships$	links$)\w[-\w_]*$"`), any valid JSON
relationships	patternProperties( "^\\w[-\\w_]*$"); links, relationships.data, meta		ActiveModel::Serializer::Adapter::JsonApi#relationships_for
relationships.data	oneOf (relationshipToOne, relationshipToMany)		ActiveModel::Serializer::Adapter::JsonApi#resource_identifier_for
relationshipToOne	anyOf(empty, linkage)
relationshipToMany	UniqueArray(linkage)
empty	null
linkage	String(type), String(id), meta	type, id	ActiveModel::Serializer::Adapter::JsonApi#primary_data_for
pagination	pageObject(first), pageObject(last), pageObject(prev), pageObject(next)		ActiveModel::Serializer::Adapter::JsonApi::PaginationLinks#serializable_hash
pagination.pageObject	oneOf(Uri, null)
jsonapi	String(version), meta		ActiveModel::Serializer::Adapter::JsonApi::ApiObjects::JsonApi
error	String(id), links, String(status), String(code), String(title), String(detail), error.source, meta
error.source	String(pointer), String(parameter)
pointer	JSON Pointer RFC6901

The http://jsonapi.org/schema makes a nice roadmap.

Success Document

• success
  • data: "$ref": "#/definitions/data"
  • included: array of unique items of type "$ref": "#/definitions/resource"
  • meta: "$ref": "#/definitions/meta"
  • links:
    • link: "$ref": "#/definitions/links"
    • pagination: "$ref": "#/definitions/pagination"
  • jsonapi: "$ref": "#/definitions/jsonapi"

Failure Document

• failure
  • errors: array of unique items of type "$ref": "#/definitions/error"
  • meta: "$ref": "#/definitions/meta"
  • jsonapi: "$ref": "#/definitions/jsonapi"

Info Document

• info
  • meta: "$ref": "#/definitions/meta"
  • links: "$ref": "#/definitions/links"
  • jsonapi: "$ref": "#/definitions/jsonapi"

Definitions

• definitions:
  • meta
  • data: oneOf (resource, array of unique resources)
  • resource
    • attributes
    • relationships
      • relationshipToOne
        • empty
        • linkage
          • meta
      • relationshipToMany
        • linkage
          • meta
    • links
    • meta
  • links
    • link
      • uri
      • href, meta
  • pagination
  • jsonapi
    • meta
  • error: id, links, status, code, title: detail: source [{pointer, type}, {parameter: {description, type}], meta