The JSON:API spec

Introduction to the JSON:API spec

Transcript

1. View Slide

2. Marco Otte-Witte
   @marcoow
   

   View Slide

3. simplabs.com
   @simplabs
   

   View Slide

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

   View Slide

5. APIs are everywhere
   

   View Slide

6. integrating (micro-)services
   

   View Slide

7. integrating with 3rd parties
   

   View Slide

8. classic server rendered web apps are
   becoming the exception
   

   View Slide

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
   

   View Slide

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
    

    View Slide

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
    

    View Slide

12. usually JSON via REST*
    *or recently GraphQL
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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,
    …
    }
    }
    

    View Slide

19. snake_case or kebap-case?
    complete updates or partial updates?
    filtering?
    sparse field sets?
    

    View Slide

20. options, options, options
    opinions, opinions, opinions
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

24. “ “ “ “
    

    View Slide

25. The Spec
    

    View Slide

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

    View Slide

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

    View Slide

28. {
    "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
    "title": "JSON API paints my bikeshed!"
    }
    }
    }
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    

    View Slide

29. Resource Objects
    represent individual resources
    

    View Slide

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

    View Slide

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

    View Slide

32. GET /articles/1
    {
    "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
    "title": "JSON API paints my bikeshed!"
    },
    "relationships": {
    "author": {
    "data":
    {
    "type": "people",
    "id": "1"
    }
    }
    }
    }
    }
    

    View Slide

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"
    }
    }
    ]
    }
    

    View Slide

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"
    }
    }
    }
    }
    }
    

    View Slide

35. CRUD
    we're not always reading data after all
    

    View Slide

36. POST /articles
    {
    "data":
    {
    "type": "articles",
    "attributes": {
    "title": "JSON API paints my bikeshed!"
    }
    }
    }
    

    View Slide

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

    View Slide

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

    View Slide

39. HTTP/1.1 204 No Content
    

    View Slide

40. DELETE /articles/1
    

    View Slide

41. HTTP/1.1 204 No Content
    

    View Slide

42. Inclusion of related resources
    as per client request
    

    View Slide

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

    View Slide

44. Sparse field sets
    for smaller response payloads
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

49. JSON API is strictly additive
    

    View Slide

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

    View Slide

51. REST can be pretty fast
    

    View Slide

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

    View Slide

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"
    

    View Slide

54. GET /articles HTTP/1.1
    Accept: application/vnd.api+json
    If-None-Match: "686897696a7c876b7e"
    

    View Slide

55. HTTP/1.1 304 Not Modified
    

    View Slide

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

    View Slide

57. Uniform resource representations
    facilitate data reuse
    

    View Slide

58. View Slide

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": "…"
    }
    },
    …
    ]
    }
    

    View Slide

60. View Slide

61. https://raw.githubusercontent.com/facebook/graphql/master/resources/GraphQL%20Logo.png
    http://graphql.org
    

    View Slide

62. View Slide

63. POST /graphql
    {
    articles {
    id
    title
    text
    author {
    id
    name
    }
    }
    }
    

    View Slide

64. View Slide

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

    View Slide

66. GraphQL opens an endpoint on your
    system that allows (somewhat) arbitrary
    queries to your data
    

    View Slide

67. "GraphQL will replace REST in the same
    way MongoDB replaced PostgreSQL."
    Tom Dale
    

    View Slide

68. "Things are going to get better for
    everyone through experimentation with
    new approaches."
    Marco Otte-Witte
    

    View Slide

69. ♥
    

    View Slide

70. Thanks
    

    View Slide

71. Q&A
    

    View Slide

72. http://simplabs.com
    @simplabs
    

    View Slide