JSON API - standards please

Slides from my Meet.JS talk on JSON API standards (JSend and JSON API specifications)

Transcript

1. JSON API standards please Michał Ostruszka | @mostruszka | michalostruszka.pl
2. every app defines own “standard” Wild, wild west
3. { “status”: “ok”, “response”: {...} }
4. { “result”: “success”, “data”: [] }
5. { “status”: 200 }
6. { “result”: “error”, “msg”: “No such user” }
7. { “status”: 404, “error”: “No such user” }
8. { “status”: 404, “errors”: [ “No such user” ] }
9. and so on...
10. sometimes even within one app Inconsistency
11. Any standards?
12. “JSend is a specification that lays down some rules for how JSON responses from web servers should be formatted” JSend
13. JSend - success { “status”: “success”, “data”: { “posts”: [...] } } required: status, data
14. JSend - failure { “status”: “fail”, “data”: { “title”: “Title is required” } } Used for invalid data responses required: status = “fail”, data
15. JSend - error { “status”: “error”, “message”: “Server goes bananas” } Used for server errors required: status = “error”, message optional: code, data
16. simple easy to follow, “data” can contain anything That’s all
17. only 41 various interpretations not always flexible enough Wait, HTTP codes?
18. “If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your anti-bikeshedding weapon.” JSON API
19. defines data format, mime type registered application/vnd.api+json relations etc Bigger spec
20. ID style URL style Flavors
21. JSON API - Simple { “posts”: [{ “id”: 1, “title”: “Hello world” }] } always as list, even for 1 item item MUST contain “id”
22. JSON API - Relationships { “posts”: [{ “id”: 1, “title”: “Hello world”, “links”: { “author”: “9” “comments”: [“1”,”2”,”3”] } }] } Client needs to know how to build author url
23. Embedded in “linked” field Save HTTP requests Compound docs
24. Same for simple resources URL Style
25. URL Style { “posts”: [{ “id”: 1, “title”: “Hello world”, “links”: { “author”: “http://example.com/author/2” } }] } client can blindly follow URLs
26. GET /posts/1?include=comments GET /posts/1?include=comments.author Selective fetching
27. Defines how to send data POST, PUT, DELETE etc Resources manipulation
28. No status in response body HTTP codes used to determine status Relies on HTTP codes
29. Once JSON API is stable, it will always be backwards compatible using a never remove, only add strategy Changes?
30. http://labs.omniti.com/labs/jsend http://jsonapi.org/ Where to find?
31. Possible adoption? Stick to standard for your project JSend looks easier Final word
32. kthxbye