JSON API

Transcript

1. None

2. Marco Otte-Witte @marcoow

3. http://simplabs.com @simplabs

4. None

5. http://jsonapi.org

6. A specification for building APIs in JSON

7. None

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

26. None

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/

63. None

64. ♥

65. http://simplabs.com @simplabs