Building a Better API with JSON:API

Building a Better API with JSON:API

222b9468cdd5429777028caff720ac38?s=128

Chris Guzman

August 20, 2017
Tweet

Transcript

  1. {json:api} A specification for building APIs in JSON

  2. {json:api} A specification for building APIs in JSON duh

  3. None
  4. None
  5. {json:api}

  6. {json:api}

  7. {"json":"api"}

  8. Why?

  9. None
  10. » Minimize requests & data between clients & servers »

    Consistency, popular among consultancies » Always backwards compatible » Stable 1.0, not dead
  11. No really

  12. History

  13. !+"+#$+%=

  14. None
  15. Spec

  16. » data: the document’s “primary data” » errors: an array

    of error objects » meta: a meta object that contains non-standard meta- information.
  17. Data

  18. { "data": { "type": "articles", "id": "1", "attributes": { "title":

    "Rails is Omakase" }, "relationships": { }, "links": { "self": "http://example.com/articles/1" }, } }
  19. Relationships

  20. { "relationships": { "author": { "links": { "self": "/articles/1/relationships/author", "related":

    "/articles/1/author" }, "data": { "type": "people", "id": "9" } } } }
  21. Meta

  22. { "meta": { "count": "42", "copyright": "Copyright 2015 Example Corp.",

    "authors": [ "Yehuda Katz", "Steve Klabnik", "Dan Gebhardt", "Tyler Kellen" ] } }
  23. Errors

  24. { "errors": [ "id": "UUID", "status": "418", "code": "42", "title":

    "You're a teapot", "detail": "The object is not short nor stout", "links": { "about": "https://httpstatuses.com/418" }, "meta": { "email": "nobody@example.com" } ] }
  25. GET /articles Accept: application/vnd.api+json GET /articles/1 Accept: application/vnd.api+json GET /articles/1/author

    Accept: application/vnd.api+json
  26. #Request comments with an article GET /articles/1?include=comments Accept: application/vnd.api+json #Request

    comments as well as the author of each of those comments GET /articles/1?include=comments.author Accept: application/vnd.api+json
  27. GET /articles?include=comments,author &fields[people]=first-name,last-name &sort=-date » fetch all articles with their

    associated comments and authors » Only be return the first and last names » Sorted by date, most recent first
  28. POST /photos { "data": { "type": "photos", "attributes": { "title":

    "Ember Hamster", "src": "http://example.com/images/productivity.png" }, "relationships": { "photographer": { "data": { "type": "people", "id": "9" } } } } }
  29. None
  30. None
  31. None