Building a Better API with JSON:API

Transcript

1. {json:api} A specification for building APIs in JSON
2. {json:api} A specification for building APIs in JSON duh
5. {json:api}
6. {json:api}
7. {"json":"api"}
8. Why?
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. !+"+#$+%=
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" } } } } }