The JSON:API spec - Speaker Deck

Slide 1

Slide 1 text

No content

Slide 2

Slide 2 text

Marco Otte-Witte @marcoow

Slide 3

Slide 3 text

simplabs.com @simplabs

Slide 4

Slide 4 text

http://jsonapi.org https://github.com/json-api/json-api/blob/gh-pages/images/jsonapi.png

Slide 5

Slide 5 text

APIs are everywhere

Slide 6

Slide 6 text

integrating (micro-)services

Slide 7

Slide 7 text

integrating with 3rd parties

Slide 8

Slide 8 text

classic server rendered web apps are becoming the exception

Slide 9

Slide 9 text

https://s3-us-west-2.amazonaws.com/s.cdpn.io/68939/angular-logo.png http://emberjs.com/images/brand/ember_Ember-Light.png http://red-badger.com/blog/wp-content/uploads/2015/04/react-logo-1000-transparent.png

Slide 10

Slide 10 text

http://www.electronicways.com/wp-content/uploads/2014/12/Android-Tablet.jpg https://cdn2.macworld.co.uk/cmsdata/features/3530504/iphone-7-jet-black.jpg

Slide 11

Slide 11 text

https://camo.githubusercontent.com/5dd01312b30468423cb45b582b83773f5a9019bb/687474703a2f2f656c656374726f6e2e61746f6d2e696f2f696d616765732f656c656374726f6e2d6c6f676f2e737667 https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/Windows_logo_-_2012.svg/2000px-Windows_logo_-_2012.svg.png https://upload.wikimedia.org/wikipedia/commons/2/22/MacOS_logo_%282017%29.svg

Slide 12

Slide 12 text

usually JSON via REST* *or recently GraphQL

Slide 13

Slide 13 text

https://twitter.com/thomasfuchs/status/604323589979049984

Slide 14

Slide 14 text

there's hundred of variations of JSON via REST

Slide 15

Slide 15 text

» curl https://api.github.com/repos/rails/rails HTTP/1.1 200 OK … { "id": 1, "name": "sinatra", … }

Slide 16

Slide 16 text

» curl -i https://api.travis-ci.org/repos/rails/rails HTTP/1.1 200 OK … { "repo": { "id": 82, "slug": "sinatra/sinatra", … } }

Slide 17

Slide 17 text

» curl https://api.github.com/repos/rails/rails HTTP/1.1 200 OK … { "id": 1, "name": "sinatra", … "owner": { "login": "rails", "id": 4223, … } }

Slide 18

Slide 18 text

» curl -i https://api.travis-ci.org/repos/rails/rails HTTP/1.1 200 OK … { "repo": { "id": 82, "slug": "sinatra/sinatra", … "last_build_id": 23436881, … } }

Slide 19

Slide 19 text

snake_case or kebap-case? complete updates or partial updates? ﬁltering? sparse ﬁeld sets?

Slide 20

Slide 20 text

options, options, options opinions, opinions, opinions

Slide 21

Slide 21 text

root level keys! plain hashes! embed relations! reference relations!

Slide 22

Slide 22 text

https://www.broxap.com/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/b/i/bikeshed_bxmwmu2.jpg_1.jpg.jpg

Slide 23

Slide 23 text

JSON API is your "anti-bikeshedding tool"

Slide 24

Slide 24 text

“ “ “ “

Slide 25

Slide 25 text

The Spec

Slide 26

Slide 26 text

Media Type application/vnd.api+json http://www.iana.org/assignments/media-types/application/vnd.api+json

Slide 27

Slide 27 text

GET /articles/1 HTTP/1.1 Accept: application/vnd.api+json

Slide 28

Slide 28 text

{ "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } } } HTTP/1.1 200 OK Content-Type: application/vnd.api+json

Slide 29

Slide 29 text

Resource Objects represent individual resources

Slide 30

Slide 30 text

GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } } }

Slide 31

Slide 31 text

GET /articles { "data": [ { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } }, { "type": "articles", "id": "2", "attributes": { "title": "Rails is Omakase" } } ] }

Slide 32

Slide 32 text

GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "1" } } } } }

Slide 33

Slide 33 text

GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "1" } } } }, "included": [ { "type": "people", "id": "1", "attributes": { "name": "Dan Gebhard" } } ] }

Slide 34

Slide 34 text

GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "links": { "self": "/articles/1/relationships/author", "related": "/articles/1/author" } } } } }

Slide 35

Slide 35 text

CRUD we're not always reading data after all

Slide 36

Slide 36 text

POST /articles { "data": { "type": "articles", "attributes": { "title": "JSON API paints my bikeshed!" } } }

Slide 37

Slide 37 text

HTTP/1.1 201 Created Location: http://example.com/articles/1 { "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } } }

Slide 38

Slide 38 text

PATCH /articles/1 { "data": { "type": "articles", "id": "1", "attributes": { "title": "json:api paints my bikeshed!" } } }

Slide 39

Slide 39 text

HTTP/1.1 204 No Content

Slide 40

Slide 40 text

DELETE /articles/1

Slide 41

Slide 41 text

HTTP/1.1 204 No Content

Slide 42

Slide 42 text

Inclusion of related resources as per client request

Slide 43

Slide 43 text

GET /articles/1?include=comments.author

Slide 44

Slide 44 text

Sparse ﬁeld sets for smaller response payloads

Slide 45

Slide 45 text

GET /articles? include=author&fields[articles]=title,body&fi elds[people]=name

Slide 46

Slide 46 text

There's more errors, ﬁltering, pagination, etc.

Slide 47

Slide 47 text

Client and Server libraries for many languages and frameworks http://jsonapi.org/implementations/

Slide 48

Slide 48 text

What's a spec worth if everyone uses a diﬀerent version?

Slide 49

Slide 49 text

JSON API is strictly additive

Slide 50

Slide 50 text

"What is he even talking about, we're all hyped up about GraphQL!!!"

Slide 51

Slide 51 text

REST can be pretty fast

Slide 52

Slide 52 text

GET /articles/1 HTTP/1.1 Accept: application/vnd.api+json

Slide 53

Slide 53 text

{ "data": { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } } } HTTP/1.1 200 OK Content-Type: application/vnd.api+json ETag: "686897696a7c876b7e"

Slide 54

Slide 54 text

GET /articles HTTP/1.1 Accept: application/vnd.api+json If-None-Match: "686897696a7c876b7e"

Slide 55

Slide 55 text

HTTP/1.1 304 Not Modified

Slide 56

Slide 56 text

HTTP/2 more parallel requests, server push, etc.

Slide 57

Slide 57 text

Uniform resource representations facilitate data reuse

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

GET /articles?include=author { "data": [ { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!", "text": "…" }, "relationships": { "author": { "data": { "type": "people", "id": "2" } } } }, … ], "included": [ { "type": "people", "id": "2", "attributes": { "name": "Dan Gebhard", "bio": "…", "imageUrl": "…" } }, … ] }

Slide 60

Slide 60 text

No content

Slide 61

Slide 61 text

https://raw.githubusercontent.com/facebook/graphql/master/resources/GraphQL%20Logo.png http://graphql.org

Slide 62

Slide 62 text

No content

Slide 63

Slide 63 text

POST /graphql { articles { id title text author { id name } } }

Slide 64

Slide 64 text

No content

Slide 65

Slide 65 text

POST /graphql { author(id: "1") { name bio imageUrl } }

Slide 66

Slide 66 text

GraphQL opens an endpoint on your system that allows (somewhat) arbitrary queries to your data

Slide 67

Slide 67 text

"GraphQL will replace REST in the same way MongoDB replaced PostgreSQL." Tom Dale

Slide 68

Slide 68 text

"Things are going to get better for everyone through experimentation with new approaches." Marco Otte-Witte