The JSON:API spec

The JSON:API spec

Introduction to the JSON:API spec

3179e6bb62dc91d29bb906ffef4fa2d4?s=128

Marco Otte-Witte

September 20, 2017
Tweet

Transcript

  1. None
  2. Marco Otte-Witte @marcoow

  3. simplabs.com @simplabs

  4. http://jsonapi.org https://github.com/json-api/json-api/blob/gh-pages/images/jsonapi.png

  5. APIs are everywhere

  6. integrating (micro-)services

  7. integrating with 3rd parties

  8. classic server rendered web apps are becoming the exception

  9. https://s3-us-west-2.amazonaws.com/s.cdpn.io/68939/angular-logo.png http://emberjs.com/images/brand/ember_Ember-Light.png http://red-badger.com/blog/wp-content/uploads/2015/04/react-logo-1000-transparent.png

  10. http://www.electronicways.com/wp-content/uploads/2014/12/Android-Tablet.jpg https://cdn2.macworld.co.uk/cmsdata/features/3530504/iphone-7-jet-black.jpg

  11. https://camo.githubusercontent.com/5dd01312b30468423cb45b582b83773f5a9019bb/687474703a2f2f656c656374726f6e2e61746f6d2e696f2f696d616765732f656c656374726f6e2d6c6f676f2e737667 https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/Windows_logo_-_2012.svg/2000px-Windows_logo_-_2012.svg.png https://upload.wikimedia.org/wikipedia/commons/2/22/MacOS_logo_%282017%29.svg

  12. usually JSON via REST* *or recently GraphQL

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

  14. there's hundred of variations of JSON via REST

  15. » curl https://api.github.com/repos/rails/rails HTTP/1.1 200 OK … { "id": 1,

    "name": "sinatra", … }
  16. » curl -i https://api.travis-ci.org/repos/rails/rails HTTP/1.1 200 OK … { "repo":

    { "id": 82, "slug": "sinatra/sinatra", … } }
  17. » curl https://api.github.com/repos/rails/rails HTTP/1.1 200 OK … { "id": 1,

    "name": "sinatra", … "owner": { "login": "rails", "id": 4223, … } }
  18. » curl -i https://api.travis-ci.org/repos/rails/rails HTTP/1.1 200 OK … { "repo":

    { "id": 82, "slug": "sinatra/sinatra", … "last_build_id": 23436881, … } }
  19. snake_case or kebap-case? complete updates or partial updates? filtering? sparse

    field sets?
  20. options, options, options opinions, opinions, opinions

  21. root level keys! plain hashes! embed relations! reference relations!

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

  23. JSON API is your "anti-bikeshedding tool"

  24. “ “ “ “

  25. The Spec

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

  27. GET /articles/1 HTTP/1.1 Accept: application/vnd.api+json

  28. { "data": { "type": "articles", "id": "1", "attributes": { "title":

    "JSON API paints my bikeshed!" } } } HTTP/1.1 200 OK Content-Type: application/vnd.api+json
  29. Resource Objects represent individual resources

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

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

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

    { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "1" } } } } }
  33. 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" } } ] }
  34. 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" } } } } }
  35. CRUD we're not always reading data after all

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

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

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

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

  40. DELETE /articles/1

  41. HTTP/1.1 204 No Content

  42. Inclusion of related resources as per client request

  43. GET /articles/1?include=comments.author

  44. Sparse field sets for smaller response payloads

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

  46. There's more errors, filtering, pagination, etc.

  47. Client and Server libraries for many languages and frameworks http://jsonapi.org/implementations/

  48. What's a spec worth if everyone uses a different version?

  49. JSON API is strictly additive

  50. "What is he even talking about, we're all hyped up

    about GraphQL!!!"
  51. REST can be pretty fast

  52. GET /articles/1 HTTP/1.1 Accept: application/vnd.api+json

  53. { "data": { "type": "articles", "id": "1", "attributes": { "title":

    "JSON API paints my bikeshed!" } } } HTTP/1.1 200 OK Content-Type: application/vnd.api+json ETag: "686897696a7c876b7e"
  54. GET /articles HTTP/1.1 Accept: application/vnd.api+json If-None-Match: "686897696a7c876b7e"

  55. HTTP/1.1 304 Not Modified

  56. HTTP/2 more parallel requests, server push, etc.

  57. Uniform resource representations facilitate data reuse

  58. None
  59. GET /articles?include=author { "data": [ { "type": "articles", "id": "1",

    "attributes": { "title": "JSON API paints my bikeshed!", "text": "…" }, "relationships": { "author": { "data": { "type": "people", "id": "2" } } } }, … ], "included": [ { "type": "people", "id": "2", "attributes": { "name": "Dan Gebhard", "bio": "…", "imageUrl": "…" } }, … ] }
  60. None
  61. https://raw.githubusercontent.com/facebook/graphql/master/resources/GraphQL%20Logo.png http://graphql.org

  62. None
  63. POST /graphql { articles { id title text author {

    id name } } }
  64. None
  65. POST /graphql { author(id: "1") { name bio imageUrl }

    }
  66. GraphQL opens an endpoint on your system that allows (somewhat)

    arbitrary queries to your data
  67. "GraphQL will replace REST in the same way MongoDB replaced

    PostgreSQL." Tom Dale
  68. "Things are going to get better for everyone through experimentation

    with new approaches." Marco Otte-Witte
  69. Thanks

  70. Q&A

  71. http://simplabs.com @simplabs