The JSON:API spec

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. ♥

70. Thanks

71. Q&A

72. http://simplabs.com @simplabs