An introduction to JSON API, the standard for building JSON-based APIs. Presented at the NH Full Stack meetup in Portsmouth, NH.
Dan Gebhardt @dgebNH FullStack March 2015
View Slide
" "" "
jsonapi.org
@wycats @steveklabnik @dgeb @tkellen
HISTORY• 2013-05-03 - Initial draft release • 2013-07-22 - Media type registration • 2014-07-04 - 1.0 RC1 • 2015-02-18 - 1.0 RC2 • 2015-03-16 - 1.0 RC3 • 2015-04-?? - 1.0
MEDIA TYPE + HTTP RULES
MEDIA TYPE + HTTP RULES“WHAT”“HOW”
MEDIA TYPEapplication/vnd.api+json
MEDIA TYPE{!"data": {!"type": "articles",!"id": "1",!"title": "JSON API paints my bikeshed!"!}!}!
MEDIA TYPE{!"data": [{!"type": "articles",!"id": "1",!"title": "JSON API paints my bikeshed!"!}, {!"type": "articles",!"id": "2",!"title": "JSON API 1.0 - An epic trilogy"!}]!}!
MEDIA TYPE{!"data": {!"type": "articles",!"id": "1",!"title": "JSON API paints my bikeshed!",!"links": {!"self": "http://example.com/articles/1",!"author": {!"self": "http://example.com/articles/1/links/author",!"related": "http://example.com/articles/1/author"!},!"comments": {!"self": "http://example.com/articles/1/links/comments",!"related": "http://example.com/articles/1/comments"!}!}!}!}!
MEDIA TYPE{!"data": {!"type": "articles",!"id": "1",!"title": "JSON API paints my bikeshed!",!"links": {!"self": "http://example.com/articles/1",!"author": {!"self": "http://example.com/articles/1/links/author",!"related": "http://example.com/articles/1/author",!"linkage": { "type": "people", "id": "9" }!},!}!},!"included": [{!"type": "people",!"id": "9",!"name": "dgeb"!}]!}
MEDIA TYPE{!"meta": {!"copyright": "Copyright 2015 Example Corp.",!"authors": [!"Yehuda Katz",!"Steve Klabnik",!"Dan Gebhardt"!]!},!"data": {!// ...!}!}!!
MEDIA TYPE{!"links": {!"self": "http://example.com/articles",!"next": "http://example.com/articles?page[offset]=20",!"last": "http://example.com/articles?page[offset]=110"!},!"data": {!// ...!}!}!
HTTP RULES• GET - Fetching resources • POST - Creating resources • PATCH - Updating resources • DELETE - Deleting resources
FETCHINGGET /articles!!{!"links": {!"self": "http://example.com/articles"!},!"data": [{!"type": "articles",!"id": "1",!"title": "JSON API paints my bikeshed!"!}, {!"type": "articles",!"id": "2",!"title": "Rails is Omakase"!}]!}
FETCHINGGET /articles/1!!{!"links": {!"self": "http://example.com/articles/1"!},!"data": {!"type": "articles",!"id": "1",!"title": "JSON API paints my bikeshed!"!}!}
FETCHING COMPOUND DOCSGET /articles/1?include=comments!!GET /articles/1?include=author,comments,comments.author!
SPARSE FIELDSETSGET /articles?fields[articles]=title,body!!GET /articles? !include=author&!fields[articles]=title,body&!fields[people]=name!
SORTINGGET /people?sort=+age!!GET /people?sort=+age,+name!!GET /people?sort=-birthday
CREATINGPOST /photos!Content-Type: application/vnd.api+json!Accept: application/vnd.api+json!!{!"data": {!"type": "photos",!"title": "Ember Hamster",!"src": "http://example.com/images/productivity.png"!}!}
UPDATINGPATCH /articles/1!Content-Type: application/vnd.api+json!Accept: application/vnd.api+json!!{!"data": {!"type": "articles",!"id": "1",!"title": "To TDD or Not"!}!}
UPDATING RELATIONSHIPSPATCH /articles/1/links/author!Content-Type: application/vnd.api+json!Accept: application/vnd.api+json!!{!"data": { "type": "people", "id": "12" }!}
UPDATING RELATIONSHIPSPATCH /articles/1/links/tags!Content-Type: application/vnd.api+json!Accept: application/vnd.api+json!!{!"data": [!{ "type": "tags", "id": "2" },!{ "type": "tags", "id": "3" }!]!}
UPDATING RELATIONSHIPSPOST /articles/1/links/comments!Content-Type: application/vnd.api+json!Accept: application/vnd.api+json!!{!"data": [!{ "type": "comments", "id": "123" }!]!}
UPDATING RELATIONSHIPSDELETE /articles/1/links/comments!Content-Type: application/vnd.api+json!Accept: application/vnd.api+json!!{!"data": [!{ "type": "comments", "id": "12" },!{ "type": "comments", "id": "13" }!]!}
EXTENSIONS• Bulk extension application/vnd.api+json; ext=bulk • JSON Patch extension application/vnd.api+json; ext=jsonpatch !• Custom extensions application/vnd.api+json; ext=my-org/custom-ext
RECOMMENDATIONS• Naming • URL Design • Filtering
IMPLEMENTATIONS• Client libs:• JavaScript • Swift • Ruby • Server libs:• JavaScript • PHP • Ruby • Python • Go • .NET
IMPLEMENTATIONS• Client libs:• Ember-data • Orbit.js • Server libs:• ActiveModel::Serializers • JSONAPI::Resources • Endpoints
REFERENCES• jsonapi.org • github.com/json-api/json-api • Twitter: @jsonapi • Freenode: #jsonapi
Thanks! @dgebNH FullStack March 2015
dgeb
bastnic
leichteckig
.png){kind=avatar}
headwaters
guikingone
kanamasa
dicoding
javiergs
star_zero
hirobe1999
manfredsteyer
kotomin_m
inouehi
maggiecrowley
chrislema
chriscoyier
speakerdeck
paigeccino
smashingmag
bluesmoon
pedronauck
lemiorhan
bkeepers
lauravandoore
cassininazir