Introducing JSON API - Speaker Deck

Slide 1

Slide 1 text

Dan Gebhardt @dgeb NH FullStack March 2015

Slide 2

Slide 2 text

" "" "

Slide 3

Slide 3 text

jsonapi.org

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

@wycats @steveklabnik @dgeb @tkellen

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

MEDIA TYPE + HTTP RULES

Slide 9

Slide 9 text

MEDIA TYPE + HTTP RULES “WHAT” “HOW”

Slide 10

Slide 10 text

MEDIA TYPE application/vnd.api+json

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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"! }]! }!

Slide 13

Slide 13 text

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"! }! }! }! }!

Slide 14

Slide 14 text

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"! }]! }

Slide 15

Slide 15 text

Slide 16

Slide 16 text

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": {! // ...! }! }!

Slide 17

Slide 17 text

HTTP RULES • GET - Fetching resources • POST - Creating resources • PATCH - Updating resources • DELETE - Deleting resources

Slide 18

Slide 18 text

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"! }]! }

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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"! }! }

Slide 24

Slide 24 text

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"! }! }

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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" }! ]! }

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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" }! ]! }

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

RECOMMENDATIONS • Naming • URL Design • Filtering

Slide 31

Slide 31 text

IMPLEMENTATIONS • Client libs: • JavaScript • Swift • Ruby • Server libs: • JavaScript • PHP • Ruby • Python • Go • .NET

Slide 32

Slide 32 text

IMPLEMENTATIONS • Client libs: • Ember-data • Orbit.js • Server libs: • ActiveModel::Serializers • JSONAPI::Resources • Endpoints

Slide 33

Slide 33 text

REFERENCES • jsonapi.org • github.com/json-api/json-api • Twitter: @jsonapi • Freenode: #jsonapi

Slide 34

Slide 34 text

Thanks! @dgeb NH FullStack March 2015