Skip to content

Latest commit

 

History

History
140 lines (116 loc) · 8.39 KB

schema.md

File metadata and controls

140 lines (116 loc) · 8.39 KB
Raw

Back to Guides

JSON API 1.0

JSON API Requests

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::IncludeTree
    • 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 AM::S::Adapter::Base#meta
success.included UniqueArray(resource) AM::S::Adapter::JsonApi#serializable_hash_for_collection
success.data data
success.links allOf (links, pagination) AM::S::Adapter::JsonApi#links_for
success.jsonapi jsonapi
failure errors, meta, jsonapi errors
failure.errors UniqueArray(error) #1004
meta Object
data oneOf (resource, UniqueArray(resource)) AM::S::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		 AM::S::Adapter::JsonApi#relationships_for
relationships.data oneOf (relationshipToOne, relationshipToMany) AM::S::Adapter::JsonApi#resource_identifier_for
relationshipToOne anyOf(empty, linkage)
relationshipToMany UniqueArray(linkage)
empty null
linkage String(type), String(id), meta type, id AM::S::Adapter::JsonApi#primary_data_for
pagination pageObject(first), pageObject(last),
pageObject(prev), pageObject(next)		 AM::S::Adapter::JsonApi::PaginationLinks#serializable_hash
pagination.pageObject oneOf(Uri, null)
jsonapi String(version), meta AM::S::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