Upgrade to Pro — share decks privately, control downloads, hide ads and more …

JSON API

JSON API

Introduction to JSON API - a talk I gave at RubyDay 2015.

3179e6bb62dc91d29bb906ffef4fa2d4?s=128

Marco Otte-Witte

November 13, 2015
Tweet

Transcript

  1. None
  2. Marco Otte-Witte @marcoow

  3. http://simplabs.com @simplabs

  4. None
  5. http://jsonapi.org

  6. A specification for building APIs in JSON

  7. None
  8. “ “ “ “

  9. “ “ “ “

  10. Why is this even needed?

  11. https://twitter.com/thomasfuchs/status/604323589979049984

  12. everybody is using RESTful JSON APIs already

  13. …but they are all different

  14. GET /repos/sinatra/sinatra { "id": 1, "name": "sinatra", … }

  15. GET /repos/sinatra/sinatra { "repo": { "id": 82, "name": "sinatra/sinatra", …

    } }
  16. GET /1.1/users/show.json? screen_name=marcoow { "id": 1, "name": "marcoow", … }

  17. GET /users/marcoow { "id": 1, "login": "marcoow", … }

  18. GET /repos/simplabs/rails_api_auth { "id": 1,
 "name": "rails_api_auth", "owner": { "id":

    1,
 "name": "simplabs", … } … }
  19. GET /repos/:repo_id/branches/master { "branches": { { "id": 1, "repository_id": 891,

    … } } }
  20. https://www.broxap.com/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/b/i/bikeshed_bxmwmu2.jpg_1.jpg.jpg

  21. JSON API is your anti bikeshedding weapon

  22. some History

  23. it started with a lengthy discussion between Yehuda Katz and

    Steve Klabnik at RailsConf 2013
  24. Yehuda wrote the first draft

  25. 1.0 released on May 29th 2015

  26. None
  27. the Goals

  28. define a generic media type that works across a broad

    set of use cases
  29. make the format similar to existing server-side framework practices

  30. having a human readable format that is also easy to

    debug
  31. ensuring ease of implementation both on the server as well

    as on the client side
  32. the Format

  33. Media Type application/vnd.api+json http://www.iana.org/assignments/media-types/application/vnd.api+json

  34. Resource Objects represent individual resources

  35. GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes":

    { "title": "JSON API paints my bikeshed!" } } }
  36. GET /articles { "data": [ { "type": "articles", "id": "1",

    "attributes": { "title": "JSON API paints my bikeshed!" } }, { "type": "articles", "id": "2", "attributes": { "title": "Rails is Omakase" } } ] }
  37. GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes":

    { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "1" } } } } }
  38. Hypermedia is part of the spec but opt-in

  39. GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes":

    { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "links": { "self": "/articles/1/relationships/author", "related": "/articles/1/author" } } } } }
  40. Inclusion of related resources is a way of reducing requests

  41. GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes":

    { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "1" } } } }, "included": [{ "type": "people", "id": "1", "attributes": { "name": "Dan Gebhard" } }] }
  42. CRUD works pretty much as you'd expect

  43. GET /articles GET /articles/1 POST /articles PATCH /articles/1 DELETE /articles/1

  44. POST /articles { "data": { "type": "articles", "attributes": { "title":

    "JSON API paints my bikeshed!" } } }
  45. HTTP/1.1 201 Created Location: http://example.com/articles/1 { "data": { "type": "articles",

    "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } } }
  46. PATCH /articles/1 { "data": { "type": "articles", "id": "1", "attributes":

    { "title": "json:api paints my bikeshed!" } } }
  47. HTTP/1.1 204 No Content

  48. DELETE /articles/1

  49. HTTP/1.1 204 No Content

  50. Advanced Features

  51. Inclusion of related resources can also be requested by the

    client
  52. GET /articles/1?include=comments.author

  53. Sparse field sets can be used to reduce the response

    size
  54. GET /articles? include=author&fields[articles]=title,body&fi elds[people]=name

  55. Bulk Operations allow creating/updating/deleting multiple resources at once

  56. POST /articles { "data": [{ "type": "articles", "attributes": { "title":

    "JSON API paints my bikeshed!" } }, { "type": "articles", "attributes": { "title": "Rails is Omakase" } }] }
  57. HTTP/1.1 201 Created { "data": [{ "type": "articles", "id": "1",

    "attributes": { "title": "JSON API paints my bikeshed!" } },{ "type": "articles", "id": "2", "attributes": { "title": "Rails is Omakase" } }] }
  58. Ruby Implementations

  59. ActiveModelSerializers supports it in 0.10.0 https://github.com/rails-api/active_model_serializers

  60. ROAR https://github.com/apotonick/roar

  61. JSONAPI::Resources https://github.com/cerebris/jsonapi-resources

  62. Client Libraries are available for many languages http://jsonapi.org/implementations/

  63. None
  64. http://simplabs.com @simplabs