Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
The JSON:API spec
Marco Otte-Witte
September 20, 2017
Programming
3
1.4k
The JSON:API spec
Introduction to the JSON:API spec
Marco Otte-Witte
September 20, 2017
Tweet
Share
More Decks by Marco Otte-Witte
See All by Marco Otte-Witte
Handling images on the web
marcoow
0
330
SSR, SPAs and PWAs
marcoow
0
310
Fast, Fast, Fast
marcoow
2
340
Feel the Glimmer - ParisJS
marcoow
1
380
Feel the Glimmer - MunichJS 11/17
marcoow
0
100
Leveraging the complete Ember Toolbelt
marcoow
0
160
Feel the Glimmer
marcoow
1
210
Templates and Logic in Ember
marcoow
0
450
Auth* with FastBoot
marcoow
2
780
Other Decks in Programming
See All in Programming
AWSにおける標的型Bot対策
hacomono
0
400
Micro Frontends with Module Federation @MicroFrontend Summit 2023
manfredsteyer
PRO
0
470
Remote SSHで行うVS Codeリモートホスト開発とトラブルシューティング
smt7174
1
440
ECS Service Connectでマイクロサービスを繋いでみた
xblood
0
530
tidy_rpart
bk_18
0
580
Findy - エンジニア向け会社紹介 / Findy Letter for Engineers
findyinc
2
42k
Hasura の Relationship と権限管理
karszawa
0
160
フロントエンドで学んだことをデータ分析で使ってみた話
daichi_igarashi
0
170
AWS App Runnerがそろそろ本番環境でも使い物になりそう
n1215
PRO
0
930
Zynq MP SoC で楽しむエッジコンピューティング ~RTLプログラミングのススメ~
ryuz88
0
310
Refactor with using `available` and `deprecated`
417_72ki
3
380
Jetpack Compose 完全に理解した
mkeeda
1
440
Featured
See All Featured
Building a Scalable Design System with Sketch
lauravandoore
451
31k
Designing Experiences People Love
moore
130
22k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
500
130k
Optimizing for Happiness
mojombo
365
64k
Debugging Ruby Performance
tmm1
67
11k
Large-scale JavaScript Application Architecture
addyosmani
499
110k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
226
16k
Robots, Beer and Maslow
schacon
154
7.3k
How to name files
jennybc
47
73k
Imperfection Machines: The Place of Print at Facebook
scottboms
254
12k
Web development in the modern age
philhawksworth
197
9.6k
The Invisible Customer
myddelton
113
12k
Transcript
None
Marco Otte-Witte @marcoow
simplabs.com @simplabs
http://jsonapi.org https://github.com/json-api/json-api/blob/gh-pages/images/jsonapi.png
APIs are everywhere
integrating (micro-)services
integrating with 3rd parties
classic server rendered web apps are becoming the exception
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
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
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
usually JSON via REST* *or recently GraphQL
https://twitter.com/thomasfuchs/status/604323589979049984
there's hundred of variations of JSON via REST
» curl https://api.github.com/repos/rails/rails HTTP/1.1 200 OK … { "id": 1,
"name": "sinatra", … }
» curl -i https://api.travis-ci.org/repos/rails/rails HTTP/1.1 200 OK … { "repo":
{ "id": 82, "slug": "sinatra/sinatra", … } }
» curl https://api.github.com/repos/rails/rails HTTP/1.1 200 OK … { "id": 1,
"name": "sinatra", … "owner": { "login": "rails", "id": 4223, … } }
» 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, … } }
snake_case or kebap-case? complete updates or partial updates? filtering? sparse
field sets?
options, options, options opinions, opinions, opinions
root level keys! plain hashes! embed relations! reference relations!
https://www.broxap.com/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/b/i/bikeshed_bxmwmu2.jpg_1.jpg.jpg
JSON API is your "anti-bikeshedding tool"
“ “ “ “
The Spec
Media Type application/vnd.api+json http://www.iana.org/assignments/media-types/application/vnd.api+json
GET /articles/1 HTTP/1.1 Accept: application/vnd.api+json
{ "data": { "type": "articles", "id": "1", "attributes": { "title":
"JSON API paints my bikeshed!" } } } HTTP/1.1 200 OK Content-Type: application/vnd.api+json
Resource Objects represent individual resources
GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes":
{ "title": "JSON API paints my bikeshed!" } } }
GET /articles { "data": [ { "type": "articles", "id": "1",
"attributes": { "title": "JSON API paints my bikeshed!" } }, { "type": "articles", "id": "2", "attributes": { "title": "Rails is Omakase" } } ] }
GET /articles/1 { "data": { "type": "articles", "id": "1", "attributes":
{ "title": "JSON API paints my bikeshed!" }, "relationships": { "author": { "data": { "type": "people", "id": "1" } } } } }
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" } } ] }
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" } } } } }
CRUD we're not always reading data after all
POST /articles { "data": { "type": "articles", "attributes": { "title":
"JSON API paints my bikeshed!" } } }
HTTP/1.1 201 Created Location: http://example.com/articles/1 { "data": { "type": "articles",
"id": "1", "attributes": { "title": "JSON API paints my bikeshed!" } } }
PATCH /articles/1 { "data": { "type": "articles", "id": "1", "attributes":
{ "title": "json:api paints my bikeshed!" } } }
HTTP/1.1 204 No Content
DELETE /articles/1
HTTP/1.1 204 No Content
Inclusion of related resources as per client request
GET /articles/1?include=comments.author
Sparse field sets for smaller response payloads
GET /articles? include=author&fields[articles]=title,body&fi elds[people]=name
There's more errors, filtering, pagination, etc.
Client and Server libraries for many languages and frameworks http://jsonapi.org/implementations/
What's a spec worth if everyone uses a different version?
JSON API is strictly additive
"What is he even talking about, we're all hyped up
about GraphQL!!!"
REST can be pretty fast
GET /articles/1 HTTP/1.1 Accept: application/vnd.api+json
{ "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"
GET /articles HTTP/1.1 Accept: application/vnd.api+json If-None-Match: "686897696a7c876b7e"
HTTP/1.1 304 Not Modified
HTTP/2 more parallel requests, server push, etc.
Uniform resource representations facilitate data reuse
None
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": "…" } }, … ] }
None
https://raw.githubusercontent.com/facebook/graphql/master/resources/GraphQL%20Logo.png http://graphql.org
None
POST /graphql { articles { id title text author {
id name } } }
None
POST /graphql { author(id: "1") { name bio imageUrl }
}
GraphQL opens an endpoint on your system that allows (somewhat)
arbitrary queries to your data
"GraphQL will replace REST in the same way MongoDB replaced
PostgreSQL." Tom Dale
"Things are going to get better for everyone through experimentation
with new approaches." Marco Otte-Witte
♥
Thanks
Q&A
http://simplabs.com @simplabs