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.

Transcript

1. Dan Gebhardt @dgeb NH FullStack March 2015
2. " "" "
3. jsonapi.org
6. @wycats @steveklabnik @dgeb @tkellen
7. 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
8. MEDIA TYPE + HTTP RULES
9. MEDIA TYPE + HTTP RULES “WHAT” “HOW”
10. MEDIA TYPE application/vnd.api+json
11. MEDIA TYPE {! "data": {! "type": "articles",! "id": "1",! "title": "JSON API paints my bikeshed!"! }! }!
12. 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"! }]! }!
13. 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"! }! }! }! }!
14. 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"! }]! }
15. MEDIA TYPE {! "meta": {! "copyright": "Copyright 2015 Example Corp.",! "authors": [! "Yehuda Katz",! "Steve Klabnik",! "Dan Gebhardt"! ]! },! "data": {! // ...! }! }! !
16. 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": {! // ...! }! }!
17. HTTP RULES • GET - Fetching resources • POST - Creating resources • PATCH - Updating resources • DELETE - Deleting resources
18. 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"! }]! }
19. FETCHING GET /articles/1! ! {! "links": {! "self": "http://example.com/articles/1"! },! "data": {! "type": "articles",! "id": "1",! "title": "JSON API paints my bikeshed!"! }! }
20. FETCHING COMPOUND DOCS GET /articles/1?include=comments! ! GET /articles/1?include=author,comments,comments.author!
21. SPARSE FIELDSETS GET /articles?fields[articles]=title,body! ! GET /articles? ! include=author&! fields[articles]=title,body&! fields[people]=name!
22. SORTING GET /people?sort=+age! ! GET /people?sort=+age,+name! ! GET /people?sort=-birthday
23. 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"! }! }
24. 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"! }! }
25. UPDATING RELATIONSHIPS PATCH /articles/1/links/author! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {! "data": { "type": "people", "id": "12" }! }
26. 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" }! ]! }
27. UPDATING RELATIONSHIPS POST /articles/1/links/comments! Content-Type: application/vnd.api+json! Accept: application/vnd.api+json! ! {! "data": [! { "type": "comments", "id": "123" }! ]! }
28. 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" }! ]! }
29. 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
30. RECOMMENDATIONS • Naming • URL Design • Filtering
31. IMPLEMENTATIONS • Client libs: • JavaScript • Swift • Ruby • Server libs: • JavaScript • PHP • Ruby • Python • Go • .NET
32. IMPLEMENTATIONS • Client libs: • Ember-data • Orbit.js • Server libs: • ActiveModel::Serializers • JSONAPI::Resources • Endpoints
33. REFERENCES • jsonapi.org • github.com/json-api/json-api • Twitter: @jsonapi • Freenode: #jsonapi
34. Thanks! @dgeb NH FullStack March 2015