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

Introducing JSON API

Introducing JSON API

An introduction to JSON API, the standard for building JSON-based APIs. Presented at the NH Full Stack meetup in Portsmouth, NH.

Dan Gebhardt

March 25, 2015
Tweet

More Decks by Dan Gebhardt

Other Decks in Programming

Transcript

  1. Dan Gebhardt

    @dgeb
    NH FullStack March 2015

    View full-size slide

  2. @wycats @steveklabnik @dgeb @tkellen

    View full-size slide

  3. HISTORY
    • 2013-05-03 - Initial draft release

    • 2013-07-22 - Media type registration

    • 2014-07-04 - 1.0 RC1

    • 2015-02-18 - 1.0 RC2

    • 2015-03-16 - 1.0 RC3

    • 2015-04-?? - 1.0

    View full-size slide

  4. MEDIA TYPE

    +

    HTTP RULES

    View full-size slide

  5. MEDIA TYPE

    +

    HTTP RULES
    “WHAT”
    “HOW”

    View full-size slide

  6. MEDIA TYPE
    application/vnd.api+json

    View full-size slide

  7. MEDIA TYPE
    {!
    "data": {!
    "type": "articles",!
    "id": "1",!
    "title": "JSON API paints my bikeshed!"!
    }!
    }!

    View full-size slide

  8. MEDIA TYPE
    {!
    "data": [{!
    "type": "articles",!
    "id": "1",!
    "title": "JSON API paints my bikeshed!"!
    }, {!
    "type": "articles",!
    "id": "2",!
    "title": "JSON API 1.0 - An epic trilogy"!
    }]!
    }!

    View full-size slide

  9. MEDIA TYPE
    {!
    "data": {!
    "type": "articles",!
    "id": "1",!
    "title": "JSON API paints my bikeshed!",!
    "links": {!
    "self": "http://example.com/articles/1",!
    "author": {!
    "self": "http://example.com/articles/1/links/author",!
    "related": "http://example.com/articles/1/author"!
    },!
    "comments": {!
    "self": "http://example.com/articles/1/links/comments",!
    "related": "http://example.com/articles/1/comments"!
    }!
    }!
    }!
    }!

    View full-size slide

  10. MEDIA TYPE
    {!
    "data": {!
    "type": "articles",!
    "id": "1",!
    "title": "JSON API paints my bikeshed!",!
    "links": {!
    "self": "http://example.com/articles/1",!
    "author": {!
    "self": "http://example.com/articles/1/links/author",!
    "related": "http://example.com/articles/1/author",!
    "linkage": { "type": "people", "id": "9" }!
    },!
    }!
    },!
    "included": [{!
    "type": "people",!
    "id": "9",!
    "name": "dgeb"!
    }]!
    }

    View full-size slide

  11. MEDIA TYPE
    {!
    "meta": {!
    "copyright": "Copyright 2015 Example Corp.",!
    "authors": [!
    "Yehuda Katz",!
    "Steve Klabnik",!
    "Dan Gebhardt"!
    ]!
    },!
    "data": {!
    // ...!
    }!
    }!
    !

    View full-size slide

  12. MEDIA TYPE
    {!
    "links": {!
    "self": "http://example.com/articles",!
    "next": "http://example.com/articles?page[offset]=20",!
    "last": "http://example.com/articles?page[offset]=110"!
    },!
    "data": {!
    // ...!
    }!
    }!

    View full-size slide

  13. HTTP RULES
    • GET - Fetching resources

    • POST - Creating resources

    • PATCH - Updating resources

    • DELETE - Deleting resources

    View full-size slide

  14. FETCHING
    GET /articles!
    !
    {!
    "links": {!
    "self": "http://example.com/articles"!
    },!
    "data": [{!
    "type": "articles",!
    "id": "1",!
    "title": "JSON API paints my bikeshed!"!
    }, {!
    "type": "articles",!
    "id": "2",!
    "title": "Rails is Omakase"!
    }]!
    }

    View full-size slide

  15. FETCHING
    GET /articles/1!
    !
    {!
    "links": {!
    "self": "http://example.com/articles/1"!
    },!
    "data": {!
    "type": "articles",!
    "id": "1",!
    "title": "JSON API paints my bikeshed!"!
    }!
    }

    View full-size slide

  16. FETCHING COMPOUND DOCS
    GET /articles/1?include=comments!
    !
    GET /articles/1?include=author,comments,comments.author!

    View full-size slide

  17. SPARSE FIELDSETS
    GET /articles?fields[articles]=title,body!
    !
    GET /articles? !
    include=author&!
    fields[articles]=title,body&!
    fields[people]=name!

    View full-size slide

  18. SORTING
    GET /people?sort=+age!
    !
    GET /people?sort=+age,+name!
    !
    GET /people?sort=-birthday

    View full-size slide

  19. CREATING
    POST /photos!
    Content-Type: application/vnd.api+json!
    Accept: application/vnd.api+json!
    !
    {!
    "data": {!
    "type": "photos",!
    "title": "Ember Hamster",!
    "src": "http://example.com/images/productivity.png"!
    }!
    }

    View full-size slide

  20. UPDATING
    PATCH /articles/1!
    Content-Type: application/vnd.api+json!
    Accept: application/vnd.api+json!
    !
    {!
    "data": {!
    "type": "articles",!
    "id": "1",!
    "title": "To TDD or Not"!
    }!
    }

    View full-size slide

  21. UPDATING RELATIONSHIPS
    PATCH /articles/1/links/author!
    Content-Type: application/vnd.api+json!
    Accept: application/vnd.api+json!
    !
    {!
    "data": { "type": "people", "id": "12" }!
    }

    View full-size slide

  22. UPDATING RELATIONSHIPS
    PATCH /articles/1/links/tags!
    Content-Type: application/vnd.api+json!
    Accept: application/vnd.api+json!
    !
    {!
    "data": [!
    { "type": "tags", "id": "2" },!
    { "type": "tags", "id": "3" }!
    ]!
    }

    View full-size slide

  23. UPDATING RELATIONSHIPS
    POST /articles/1/links/comments!
    Content-Type: application/vnd.api+json!
    Accept: application/vnd.api+json!
    !
    {!
    "data": [!
    { "type": "comments", "id": "123" }!
    ]!
    }

    View full-size slide

  24. UPDATING RELATIONSHIPS
    DELETE /articles/1/links/comments!
    Content-Type: application/vnd.api+json!
    Accept: application/vnd.api+json!
    !
    {!
    "data": [!
    { "type": "comments", "id": "12" },!
    { "type": "comments", "id": "13" }!
    ]!
    }

    View full-size slide

  25. EXTENSIONS
    • Bulk extension

    application/vnd.api+json; ext=bulk

    • JSON Patch extension

    application/vnd.api+json; ext=jsonpatch

    !
    • Custom extensions

    application/vnd.api+json; ext=my-org/custom-ext

    View full-size slide

  26. RECOMMENDATIONS
    • Naming

    • URL Design

    • Filtering

    View full-size slide

  27. IMPLEMENTATIONS
    • Client libs:
    • JavaScript

    • Swift

    • Ruby

    • Server libs:
    • JavaScript

    • PHP

    • Ruby

    • Python

    • Go

    • .NET

    View full-size slide

  28. IMPLEMENTATIONS
    • Client libs:
    • Ember-data

    • Orbit.js

    • Server libs:
    • ActiveModel::Serializers

    • JSONAPI::Resources

    • Endpoints

    View full-size slide

  29. REFERENCES
    • jsonapi.org

    • github.com/json-api/json-api

    • Twitter: @jsonapi

    • Freenode: #jsonapi

    View full-size slide

  30. Thanks!

    @dgeb
    NH FullStack March 2015

    View full-size slide