Introducing JSON API

Introducing JSON API

An introduction to JSON API, the standard for building JSON-based APIs. Presented at the NH Full Stack meetup in Portsmouth, NH.

E01ec1de2f7783812d2235a6a9aaaeea?s=128

Dan Gebhardt

March 25, 2015
Tweet

Transcript

  1. Dan Gebhardt @dgeb NH FullStack March 2015

  2. " "" "

  3. jsonapi.org

  4. None
  5. None
  6. @wycats @steveklabnik @dgeb @tkellen

  7. 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
  8. MEDIA TYPE + HTTP RULES

  9. MEDIA TYPE + HTTP RULES “WHAT” “HOW”

  10. MEDIA TYPE application/vnd.api+json

  11. MEDIA TYPE {! "data": {! "type": "articles",! "id": "1",! "title":

    "JSON API paints my bikeshed!"! }! }!
  12. 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"! }]! }!
  13. 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"! }! }! }! }!
  14. 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"! }]! }
  15. MEDIA TYPE {! "meta": {! "copyright": "Copyright 2015 Example Corp.",!

    "authors": [! "Yehuda Katz",! "Steve Klabnik",! "Dan Gebhardt"! ]! },! "data": {! // ...! }! }! !
  16. 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": {! // ...! }! }!
  17. HTTP RULES • GET - Fetching resources • POST -

    Creating resources • PATCH - Updating resources • DELETE - Deleting resources
  18. FETCHING GET /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"! }]! }
  19. FETCHING GET /articles/1! ! {! "links": {! "self": "http://example.com/articles/1"! },!

    "data": {! "type": "articles",! "id": "1",! "title": "JSON API paints my bikeshed!"! }! }
  20. FETCHING COMPOUND DOCS GET /articles/1?include=comments! ! GET /articles/1?include=author,comments,comments.author!

  21. SPARSE FIELDSETS GET /articles?fields[articles]=title,body! ! GET /articles? ! include=author&! fields[articles]=title,body&!

    fields[people]=name!
  22. SORTING GET /people?sort=+age! ! GET /people?sort=+age,+name! ! GET /people?sort=-birthday

  23. CREATING POST /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"! }! }
  24. UPDATING PATCH /articles/1! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {! "data":

    {! "type": "articles",! "id": "1",! "title": "To TDD or Not"! }! }
  25. UPDATING RELATIONSHIPS PATCH /articles/1/links/author! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {!

    "data": { "type": "people", "id": "12" }! }
  26. UPDATING RELATIONSHIPS PATCH /articles/1/links/tags! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {!

    "data": [! { "type": "tags", "id": "2" },! { "type": "tags", "id": "3" }! ]! }
  27. UPDATING RELATIONSHIPS POST /articles/1/links/comments! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {!

    "data": [! { "type": "comments", "id": "123" }! ]! }
  28. UPDATING RELATIONSHIPS DELETE /articles/1/links/comments! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {!

    "data": [! { "type": "comments", "id": "12" },! { "type": "comments", "id": "13" }! ]! }
  29. 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
  30. RECOMMENDATIONS • Naming • URL Design • Filtering

  31. IMPLEMENTATIONS • Client libs: • JavaScript • Swift • Ruby

    • Server libs: • JavaScript • PHP • Ruby • Python • Go • .NET
  32. IMPLEMENTATIONS • Client libs: • Ember-data • Orbit.js • Server

    libs: • ActiveModel::Serializers • JSONAPI::Resources • Endpoints
  33. REFERENCES • jsonapi.org • github.com/json-api/json-api • Twitter: @jsonapi • Freenode:

    #jsonapi
  34. Thanks! @dgeb NH FullStack March 2015