The JSON:API spec

Introduction to the JSON:API spec

Transcript

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
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": "…" } }, … ] }
61. https://raw.githubusercontent.com/facebook/graphql/master/resources/GraphQL%20Logo.png http://graphql.org
63. POST /graphql { articles { id title text author { id name } } }
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