Skip to content

Commit cf34a66

Browse files
bf4bf4
committed
Mapping JSON API spec / schema to AMS [ci skip]
1 parent 48b041e commit cf34a66

File tree

2 files changed

+504
-0
lines changed

2 files changed

+504
-0
lines changed

‎docs/jsonapi/schema.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
[![JSON API 1.0](https://img.shields.io/badge/JSON%20API-1.0-lightgrey.svg)](http://jsonapi.org/)
2+
3+
## JSON API Requests
4+
5+
[Query Parameters Spec](http://jsonapi.org/format/#query-parameters)
6+
7+
Headers:
8+
9+
- Request: `Accept: application/vnd.api+json`
10+
- Response: `Content-Type: application/vnd.api+json`
11+
12+
### [Fetching Data](http://jsonapi.org/format/#fetching)
13+
14+
A server MUST support fetching resource data for every URL provided as:
15+
16+
- a `self` link as part of the top-level links object
17+
- a `self` link as part of a resource-level links object
18+
- a `related` link as part of a relationship-level links object
19+
20+
Example supported requests
21+
22+
- Individual resource or collection
23+
- GET /articles
24+
- GET /articles/1
25+
- GET /articles/1/author
26+
- Relationships
27+
- GET /articles/1/relationships/comments
28+
- GET /articles/1/relationships/author
29+
- Optional: [Inclusion of related resources](http://jsonapi.org/format/#fetching-includes) `ActiveModel::Serializer::Fieldset`
30+
- GET /articles/1?`include`=comments
31+
- GET /articles/1?`include`=comments.author
32+
- GET /articles/1?`include`=author,comments.author
33+
- GET /articles/1/relationships/comments?`include`=comments.author
34+
- Optional: [Sparse Fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets) `ActiveModel::Serializer::Fieldset`
35+
- GET /articles?`include`=author&`fields`[articles]=title,body&`fields`[people]=name
36+
- Optional: [Sorting](http://jsonapi.org/format/#fetching-sorting)
37+
- GET /people?`sort`=age
38+
- GET /people?`sort`=age,author.name
39+
- GET /articles?`sort`=-created,title
40+
- Optional: [Pagination](http://jsonapi.org/format/#fetching-pagination)
41+
- GET /articles?`page`[number]=3&`page`[size]=1
42+
- Optional: [Filtering](http://jsonapi.org/format/#fetching-filtering)
43+
- GET /comments?`filter`[post]=1
44+
- GET /comments?`filter`[post]=1,2
45+
- GET /comments?`filter`[post]=1,2
46+
47+
### [CRUD Actions](http://jsonapi.org/format/#crud)
48+
49+
### [Asynchronous Processing](http://jsonapi.org/recommendations/#asynchronous-processing)
50+
51+
### [Bulk Operations Extension](http://jsonapi.org/extensions/bulk/)
52+
53+
## JSON API Document Schema
54+
55+
| JSON API object | JSON API properties | Required | ActiveModelSerializers representation |
56+
|-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
57+
| schema | oneOf (success, failure, info) | |
58+
| success | data, included, meta, links, jsonapi | | ActiveModel::SerializableResource
59+
| success.meta | meta | | ActiveModel::Serializer::Adapter::Base#meta
60+
| success.included | UniqueArray(resource) | | ActiveModel::Serializer::Adapter::JsonApi#serializable_hash_for_collection
61+
| success.data | data | |
62+
| success.links | allOf (links, pagination) | | ActiveModel::Serializer::Adapter::JsonApi#links_for
63+
| success.jsonapi | jsonapi | |
64+
| failure | errors, meta, jsonapi | errors |
65+
| failure.errors | UniqueArray(error) | | #1004
66+
| meta | Object | |
67+
| data | oneOf (resource, UniqueArray(resource)) | | ActiveModel::Serializer::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
68+
| resource | String(type), String(id), attributes, relationships, links, meta | type, id | ActiveModel::Serializer::Adapter::JsonApi#primary_data_for
69+
| links | Uri(self), Link(related) | | #1028, #1246, #1282
70+
| link | oneOf (linkString, linkObject) | |
71+
| link.linkString | Uri | |
72+
| link.linkObject | Uri(href), meta | href |
73+
| attributes | patternProperites(`"^(?!relationships$|links$)\\w[-\\w_]*$"`), any valid JSON | | ActiveModel::Serializer#attributes, ActiveModel::Serializer::Adapter::JsonApi#resource_object_for
74+
| relationships | patternProperites(`"^\\w[-\\w_]*$"`); links, relationships.data, meta | | ActiveModel::Serializer::Adapter::JsonApi#relationships_for
75+
| relationships.data | oneOf (relationshipToOne, relationshipToMany) | | ActiveModel::Serializer::Adapter::JsonApi#resource_identifier_for
76+
| relationshipToOne | anyOf(empty, linkage) | |
77+
| relationshipToMany | UniqueArray(linkage) | |
78+
| empty | null | |
79+
| linkage | String(type), String(id), meta | type, id | ActiveModel::Serializer::Adapter::JsonApi#primary_data_for
80+
| pagination | pageObject(first), pageObject(last), pageObject(prev), pageObject(next) | | ActiveModel::Serializer::Adapter::JsonApi::PaginationLinks#serializable_hash
81+
| pagination.pageObject | oneOf(Uri, null) | |
82+
| jsonapi | String(version), meta | | ActiveModel::Serializer::Adapter::JsonApi::ApiObjects::JsonApi
83+
| error | String(id), links, String(status), String(code), String(title), String(detail), error.source, meta | |
84+
| error.source | String(pointer), String(parameter) | |
85+
| pointer | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901) | |
86+
87+
88+
The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
89+
90+
### Success Document
91+
- [ ] success
92+
- [ ] data: `"$ref": "#/definitions/data"`
93+
- [ ] included: array of unique items of type `"$ref": "#/definitions/resource"`
94+
- [ ] meta: `"$ref": "#/definitions/meta"`
95+
- [ ] links:
96+
- [ ] link: `"$ref": "#/definitions/links"`
97+
- [ ] pagination: ` "$ref": "#/definitions/pagination"`
98+
- [ ] jsonapi: ` "$ref": "#/definitions/jsonapi"`
99+
100+
### Failure Document
101+
102+
- [ ] failure
103+
- [ ] errors: array of unique items of type ` "$ref": "#/definitions/error"`
104+
- [ ] meta: `"$ref": "#/definitions/meta"`
105+
- [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
106+
107+
### Info Document
108+
109+
- [ ] info
110+
- [ ] meta: `"$ref": "#/definitions/meta"`
111+
- [ ] links: `"$ref": "#/definitions/links"`
112+
- [ ] jsonapi: ` "$ref": "#/definitions/jsonapi"`
113+
114+
### Definitions
115+
116+
- [ ] definitions:
117+
- [ ] meta
118+
- [ ] data: oneOf (resource, array of unique resources)
119+
- [ ] resource
120+
- [ ] attributes
121+
- [ ] relationships
122+
- [ ] relationshipToOne
123+
- [ ] empty
124+
- [ ] linkage
125+
- [ ] meta
126+
- [ ] relationshipToMany
127+
- [ ] linkage
128+
- [ ] meta
129+
- [ ] links
130+
- [ ] meta
131+
- [ ] links
132+
- [ ] link
133+
- [ ] uri
134+
- [ ] href, meta
135+
- [ ] pagination
136+
- [ ] jsonapi
137+
- [ ] meta
138+
- [ ] error: id, links, status, code, title: detail: source [{pointer, type}, {parameter: {description, type}], meta

0 commit comments

Comments
 (0)