@nonsensery
* Accuracy not guaranteed
— jsonapi.org/about
— github.com/json-api/json-api/pull/234
— github.com/json-api/json-api/pull/727
— jsonapi.org/status
application/vnd.api+json
PATCH /posts/9 HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
…
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
…
{
"data": {
"type": "posts",
"id": "7",
"attributes": {
…
},
"relationships": {
…
}
}
}
Resources and Collections have unique URLs.
HTTP methods define the actions to take.
Action | Method | Response Status* |
---|---|---|
Fetch | GET | 200 OK |
Create | POST | 201 Created or 204 No Content |
Modify | PATCH | 200 OK or 204 No Content |
Destroy | DELETE | 204 No Content or 200 OK |
* These are just examples. Many other HTTP status codes are allowed, like 404 (Not Found) when fetching a resource that doesn't exist.
Responses (can) include URLs for interacting with the resources and collections they contain.
"links": {
"self": "http://awesome.sauce/posts/",
"next": "http://awesome.sauce/posts?page[offset]=2",
"last": "http://awesome.sauce/posts?page[offset]=10"
}
"comments": {
"links": {
"self": "/posts/1/relationships/comments",
"related": "/posts/1/comments"
}
}
{
"meta": { "whateva": "you", "like": "brah" },
…
"data": {
"meta": { "here": "too", "dog": [] },
…
"relationships": {
"author": {
"type": "people",
"id": "9",
"meta": { "yup.": "#dealwithit" }
},
…
}
}
}
{
"errors": [{
"title": "Request Denied",
"detail": "Ah ah ah, you didn't say the magic word.",
"status": "403",
"code": "1124",
"id": "2d9f03d5-12c1-4476-ac5f-1544412e85c5",
"links": { "about": "http://youtu.be/RfiQYRn7fBg" },
"meta": { "here too?": true }
}, {
"title": "Invalid Parameter",
"status": "400",
"source": {
"parameter": "fields[posts]"
}
}]
}
/posts?include=author,comments,comments.author
/posts?fields[post]=title,date
/posts?sort=date&page[number]=2&filter[tags]=popular
type
and id
.{
"type": "posts",
"id": "7"
}
An object with only type
and id
is called a Resource Identifier Object.
We'll see more of them soon…
{
"type": "posts",
"id": "7",
"attributes": {
"title": "JSON API paints my bikeshed!",
"published": {
"year": "2015",
"month": "06",
"day": "30"
},
"cover-photos": [
"http://giphy.com/embed/oOAuubU8LEI0w",
"http://giphy.com/embed/IhGwYlCgBOww0"
]
}
}
Primitives
Objects
Arrays
{
"type": "posts",
"id": "7",
"relationships": {
"author": {
"data": { "type": "people", "id": "9" }
},
"comments": {
"data": [
{ "type": "comments", "id": "5" },
{ "type": "comments", "id": "12" }
]
}
}
}
To-One
To-Many
… Hey, look — Resource Identifier Objects!
{
"type": "posts",
"id": "7",
"relationships": {
"author": {
"links": { "related": "/posts/7/author" }
},
"comments": {
"links": { "related": "/posts/7/comments" }
}
}
}
(via Hypermedia URLs)
Update to-one relationships with PATCH.
Update to-many relationships with PATCH, POST and DELETE.
/some-fish-swim-left
{ "type": "sharks", … }
"first-name": "Wehadababy"
"last-name": "Itsaboy"
"first_name": "Wehadababy"
"last_name": "Itsaboy"
{ "type": "shark", … }
/some/fish/swim/right
vs.
vs.
vs.
Getting [our models] into the browser requires every developer write custom, imperative code. It's a colossal waste of human time and energy.
I believe JSONAPI dropped the recom-
mendation that these keys be dasherized?
the url should be /posts here. They are always pluralized.
This is currently intentional as JSON-API does not state anything about URLs being singular/plural.
types are serialized to, and expected to be plural dasherized when received from the server
member names are serialized to, and expected to be dasherized when received from the server
URLs are … plural dasherized by default
API changes are opt-in today, default in Ember 2.0
Ember Data, Backbone, iOS and Ruby client libraries exist
They're probably more mature than your code…