active_model_serializers/docs/jsonapi/schema.md

Back to Guides

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 JSONAPI::IncludeDirective
  • 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		AM::SerializableResource
success.meta	meta		AMS::Adapter::Base#meta
success.included	UniqueArray(resource)		AMS::Adapter::JsonApi#serializable_hash_for_collection
success.data	data
success.links	allOf (links, pagination)		AMS::Adapter::JsonApi#links_for
success.jsonapi	jsonapi
failure	errors, meta, jsonapi	errors	AMS::Adapter::JsonApi#failure_document, #1004
failure.errors	UniqueArray(error)		AM::S::ErrorSerializer, #1004
meta	Object
data	oneOf (resource, UniqueArray(resource))		AMS::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
resource	String(type), String(id), attributes, relationships, links, meta	type, id	AM::S::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		AMS::Adapter::JsonApi#relationships_for
relationships.data	oneOf (relationshipToOne, relationshipToMany)		AMS::Adapter::JsonApi#resource_identifier_for
relationshipToOne	anyOf(empty, linkage)
relationshipToMany	UniqueArray(linkage)
empty	null
linkage	String(type), String(id), meta	type, id	AMS::Adapter::JsonApi#primary_data_for
pagination	pageObject(first), pageObject(last), pageObject(prev), pageObject(next)		AMS::Adapter::JsonApi::PaginationLinks#serializable_hash
pagination.pageObject	oneOf(Uri, null)
jsonapi	String(version), meta		AMS::Adapter::JsonApi::Jsonapi#as_json
error	String(id), links, String(status), String(code), String(title), String(detail), error.source, meta		AM::S::ErrorSerializer, AMS::Adapter::JsonApi::Error.resource_errors
error.source	String(pointer), String(parameter)		AMS::Adapter::JsonApi::Error.error_source
pointer	JSON Pointer RFC6901		AMS::JsonPointer

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: a unique identifier for this particular occurrence of the problem.
    • links: a links object containing the following members:
      • about: a link that leads to further details about this particular occurrence of the problem.
    • status: the HTTP status code applicable to this problem, expressed as a string value.
    • code: an application-specific error code, expressed as a string value.
    • title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    • detail: a human-readable explanation specific to this occurrence of the problem.
    • source: an object containing references to the source of the error, optionally including any of the following members:
      • pointer: a JSON Pointer RFC6901 to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
      • parameter: a string indicating which query parameter caused the error.
    • meta: a meta object containing non-standard meta-information about the error.