Upgrade to Pro — share decks privately, control downloads, hide ads and more …

JSON API

JSON API

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

Marco Otte-Witte

November 13, 2015
Tweet

More Decks by Marco Otte-Witte

Other Decks in Technology

Transcript

  1. Marco Otte-Witte
    @marcoow

    View full-size slide

  2. http://simplabs.com
    @simplabs

    View full-size slide

  3. http://jsonapi.org

    View full-size slide

  4. A specification for building APIs in JSON

    View full-size slide

  5. “ “ “ “

    View full-size slide

  6. “ “ “ “

    View full-size slide

  7. Why is this even needed?

    View full-size slide

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

    View full-size slide

  9. everybody is using RESTful JSON APIs
    already

    View full-size slide

  10. …but they are all different

    View full-size slide

  11. GET /repos/sinatra/sinatra
    {
    "id": 1,
    "name": "sinatra",

    }

    View full-size slide

  12. GET /repos/sinatra/sinatra
    {
    "repo": {
    "id": 82,
    "name": "sinatra/sinatra",

    }
    }

    View full-size slide

  13. GET /1.1/users/show.json?
    screen_name=marcoow
    {
    "id": 1,
    "name": "marcoow",

    }

    View full-size slide

  14. GET /users/marcoow
    {
    "id": 1,
    "login": "marcoow",

    }

    View full-size slide

  15. GET /repos/simplabs/rails_api_auth
    {
    "id": 1,

    "name": "rails_api_auth",
    "owner": {
    "id": 1,

    "name": "simplabs",

    }

    }

    View full-size slide

  16. GET /repos/:repo_id/branches/master
    {
    "branches": {
    {
    "id": 1,
    "repository_id": 891,

    }
    }
    }

    View full-size slide

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

    View full-size slide

  18. JSON API is your anti bikeshedding
    weapon

    View full-size slide

  19. some History

    View full-size slide

  20. it started with a lengthy discussion
    between Yehuda Katz and Steve Klabnik
    at RailsConf 2013

    View full-size slide

  21. Yehuda wrote the first draft

    View full-size slide

  22. 1.0 released on May 29th 2015

    View full-size slide

  23. define a generic media type that works
    across a broad set of use cases

    View full-size slide

  24. make the format similar to existing
    server-side framework practices

    View full-size slide

  25. having a human readable format that is
    also easy to debug

    View full-size slide

  26. ensuring ease of implementation both
    on the server as well as on the client
    side

    View full-size slide

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

    View full-size slide

  28. Resource Objects
    represent individual resources

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  32. Hypermedia
    is part of the spec but opt-in

    View full-size slide

  33. 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 full-size slide

  34. Inclusion of related resources
    is a way of reducing requests

    View full-size slide

  35. 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 full-size slide

  36. CRUD
    works pretty much as you'd expect

    View full-size slide

  37. GET /articles
    GET /articles/1
    POST /articles
    PATCH /articles/1
    DELETE /articles/1

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  41. HTTP/1.1 204 No Content

    View full-size slide

  42. DELETE /articles/1

    View full-size slide

  43. HTTP/1.1 204 No Content

    View full-size slide

  44. Advanced Features

    View full-size slide

  45. Inclusion of related resources
    can also be requested by the client

    View full-size slide

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

    View full-size slide

  47. Sparse field sets
    can be used to reduce the response size

    View full-size slide

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

    View full-size slide

  49. Bulk Operations
    allow creating/updating/deleting
    multiple resources at once

    View full-size slide

  50. POST /articles
    {
    "data": [{
    "type": "articles",
    "attributes": {
    "title": "JSON API paints my bikeshed!"
    }
    }, {
    "type": "articles",
    "attributes": {
    "title": "Rails is Omakase"
    }
    }]
    }

    View full-size slide

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

    View full-size slide

  52. Ruby Implementations

    View full-size slide

  53. ActiveModelSerializers
    supports it in 0.10.0
    https://github.com/rails-api/active_model_serializers

    View full-size slide

  54. ROAR
    https://github.com/apotonick/roar

    View full-size slide

  55. JSONAPI::Resources
    https://github.com/cerebris/jsonapi-resources

    View full-size slide

  56. Client Libraries
    are available for many languages
    http://jsonapi.org/implementations/

    View full-size slide

  57. http://simplabs.com
    @simplabs

    View full-size slide