JSON API

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

Transcript

2. Marco Otte-Witte @marcoow
3. http://simplabs.com @simplabs
5. http://jsonapi.org
6. A specification for building APIs in JSON
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
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/
64. ♥
65. http://simplabs.com @simplabs