Jan Kronquist, profile picture
Uploaded byJan Kronquist
PDF, PPTX2,047 views

Hypermedia APIs - GeekOut

The document discusses hypermedia APIs, particularly in the context of REST and the Richardson Maturity Model. It details the various maturity levels of RESTful APIs, the significance of hypermedia in API development, and practical examples related to a rock-paper-scissors game that illustrate the concepts. It emphasizes how hypermedia can simplify client development by reducing the need for constructing URLs and minimizing business logic.

Download as PDF, PPTX
Hypermedia APIs @jankronquist
Hypermedia API:s @ Jayway Rickard Öberg (~2010)! Qi4j & Streamflow! Usecases as your API! Mattias Arthursson & Karl-Johan Stenflo (~2011)! JAX-RS-HATEOAS! HATEOAS with Standard Java APIs! Mads Enevoldsen & Jan Kronquist (~2011)! Forest (CQS conventions, sensible default links, constraints...)! Gustaf Nilsson Kotte (~2012)! Adaptive HTML as your API
Outline Example domain! REST introduction (Richardson maturity model)! Exploring media types! html! collection+json! hal+json
Example domain
Rock - Paper - Scissors
Opening gambit http://www.worldrps.com/gambit-play
Opening gambit http://www.worldrps.com/gambit-play
http://rps.com The future Facebook of Rock Paper Scissors! Millions of users! Many games per user
Playing the game Player A Player B Server rock paper Player B: paper Player A: rock Game 123 Game 123 winner: Player B loser: Player A CREATED WAITING GAME WON GAME TIED any move other move (victory) other move (tie) T
Introducing REST
Towards REST REST architectural style! Defined by Roy Fielding ! Richardson maturity model http://martinfowler.com/articles/richardsonMaturityModel.html
Level 0 - Not at all RESTful Single resource, single verb! Examples:! SOAP, XML-RPC, JSON-RPC
Level 0 - Example POST /api --> { "method": “viewGame", "params": ["123"]} <-- { "result": { "state": "waiting"}, "error": null} POST /api --> { "method": "makeMove", "params": ["123","rock"]} <-- { "result": { "state": "won", "winner": "player1", "loser": "player2"}, "error": null}
Level 0 - Analysis HTTP as transport protocol! Problems! No client side caching! Tight coupling
Level 0 - In the wild JSON/RPC over HTTP! Why?! Simplicity! Track all user actions! If it ain’t broke, don't fix it
Level 1 - Resources Many resources, single verb! /api/games/123 /api/players/player1 Almost “object oriented”
Level 1 - Example POST /api/games/123 --> { "method": "viewGame"} <-- { "result": { "state": "waiting"}, "error": null} POST /api/games/123 --> { "method": "makeMove", "params": ["rock"]} <-- { "result": { "state": "won", "winner": "player1", "loser": "player2"}, "error": null}
Level 1 - Analysis Still just using HTTP as transport
Level 2 - Verbs Resources, verb and status codes!! GET, POST, PUT, DELETE... 200 OK, 304 Not Modified, 404 Not found… RESTish! Uniform interface
HTTP 101 GET - safe! POST - danger!! PUT - idempotent! ! Note! GET will not modify the resource, but other clients might! Interleaving other requests might break idempotency
GET /api/games/123 <-- 200 OK <-- { "state": "waiting"} POST /api/games/123 --> { "move": "rock"} <-- 200 OK <-- { "state": "won", "winner": "player1", "loser": “player2"} Level 2 - Example
GET /api/games/123 <-- 200 OK <-- { "state": "waiting"} POST /api/games/123 --> Content-Type: application/json --> { "move": "rock"} <-- 200 OK <-- { "state": "won", "winner": "player1", "loser": "player2"} Level 2 - Mediatype json
Level 2 - Mediatype form GET /api/games/123 <-- 200 OK <-- { "state": "waiting"} POST /api/games/123 --> Content-Type: application/x-www-form-urlencoded --> move=rock <-- 200 OK <-- { "state": "won", "winner": "player1", "loser": "player2"} $ curl -d move=rock http://rps.com/api/games/123
Level 2 - In the wild Verbs: GET, DELETE, PUT! Resources: buckets, objects, acls, policies…! Why?! CRUD operations! GET allows caching
Level 2 - Analysis Using HTTP, not fighting it! Problems! Client must construct URLs! Client must contain business rules
GET /api/games <-- 200 OK <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "items": [{"id": "111", "players": ["jan", "cecilia"]}, {"id": "222", "players": ["jan", "mike"]}, {"id": "333", "players": ["cecilia", "mike"]}, ...]} Level 2 - Constructing URLs GET /api/games?offset=10 GET /api/games?page=2 How to navigate to page 2?
GET /api/games <-- 200 OK <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "items": [{"id": "111", "players": ["jan", "cecilia"]}, {"id": "222", "players": ["jan", "mike"]}, {"id": "333", "players": ["cecilia", "mike"]}, ...]} Level 2 - Constructing URLs GET /api/games/{game.id} Navigating to game
Level 2 - Business logic GET /api/games/123 <-- 200 OK <-- { "state": "waiting", "players": ["ply1", "ply2"], "moves": { "ply1" : true} } Should the client display the move selector?
Level 2 - Business logic solved? GET /api/games/123 <-- 200 OK <-- { "state": "waiting", "players": ["ply1", "ply2"], "moves": { "ply1" : true}, "shouldMove": true }
Level 3 - Hypermedia Controls Links & forms! REST as defined by Roy Fielding Hypermedia is defined by the presence of application control information embedded within, ! or as a layer above, the presentation of information The simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions.
GET /api/games <-- 200 OK <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "next": "/api/games?offset=10", "items": [{"href": "/api/games/111", "players": ["jan", "cecilia"]}, {"href": "/api/games/222", "players": ["jan", "mike"]}, {"href": "/api/games/333" "players": ["cecilia", "mike"]}, ...]} Level 3 - Example (links)
Level 3 - Example (form) <html> <body> <ol id="players"> <li>Jan</li> <li>Cecilia</li> </ol> <form action="/api/games/111" method="POST"> <select name="move"> <option value="rock">Rock</option> <option value="paper">Paper</option> <option value="scissors">Scissors</option> </select> <input type="submit"/> </form> </body> </html>
Level 3 - Opportunity: Extra moves <select name="move"> <option value="rock">Rock</option> <option value="paper">Paper</option> <option value="scissors">Scissors</option> <option value="lizard">Lizard</option> <option value="spock">Spock</option> </select>
Level 3 - Changing the rules For one of the players: Flip a coin! head - he must play rock! tail - he can play whatever he wants! ! How can the other player take advantage of this? http://blog.gtorangebuilder.com/2014/04/gto-brain-teaser-1-exploitation-and.html <select name="move"> <option value="rock">Rock</option> </select>
Level 3 - In the wild
Media types & other tools
Media types Format! application/json, text/xml, text/plain, text/csv! Domain specific! text/vcard, text/calendar, application/calendar+json! Hypermedia! text/html, application/xhtml+xml! application/vnd.collection+json, application/vnd.hal+json! application/vnd.siren+json, application/vnd.amundsen-uber+json
GET /api/games <-- 200 OK <-- Content-Type: application/json <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "next": "/api/games?offset=10", ... } json
xhtml GET /api/games <-- 200 OK <-- Content-Type: application/xhtml+xml <-- <html> <body> <a href="/api/games?offset=10">Next</a> <div id="totalCount">23</div> <ol id="games"> <li>...</li> <li>...</li> </ol> </body> </html>
collection+json CRUD for collections of objects! Parts of the document:! items! links! queries! templates! errors
GET /api/games <-- 200 OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games", "links" : [ {"rel" : "next", "href" : "/api/games?offset=10"} ], "items" : [ { ... }, { ... } ] } } collection+json
Anatomy of a Link target url (href)! human readable string (title)! semantic information (rel)! returned media types (type)! ! http method (method)! secondary key (name)! support media types for requests (accept) RFC 5988
Standard rels item! collection! next! edit! enclosure! latest-version! self http://www.iana.org/assignments/link-relations/link-relations.xml
Custom rels Register with IANA :-)! Just make up your own :-)! move! URI! http://rps.com/rels/move! CURIE! rps:move! http://rps.com/rels/{rel}
Forms / templates More than links! Allow user input! May provide! Default values! Data types! Possible values
html form <html> <body> <ol id="players"> <li>Jan</li> <li>Cecilia</li> </ol> <form action="/api/games/111" method=“POST" name="move"> <select name="move"> <option value="rock">Rock</option> <option value="paper">Paper</option> <option value="scissors">Scissors</option> </select> <input type="submit"/> </form> </body> </html>
GET /api/games/111 <-- 200 OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games/111", "template" : { "data" : [{ "name" : "move", "value" : "", "prompt" : "Your move" }] } } } collection+json template for writes
Forced resource structure Collection of games /api/games/ Game 111 /api/games/111 Collection of moves for game 111 /api/games/111/moves Player 1 move for game 111 /api/games/111/moves/ply1 item rps:moves item
GET /api/games/111 <-- 200 OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games/111", "links" : [ {"rel" : "rps:moves", "href" : "/api/games/111/moves"} ], ... } } The game links to moves
GET /api/games/111/moves <-- 200 OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games/111/moves", "template" : { "data" : { "name" : "move", "value" : "", "prompt" : "Your move" } } } } moves collection contain template
URI templates Constructing paths
 
 Form-style! Making a move
 
 Creating a new game RFC 6570 "http://rps.com/api/games/111{?move}" "http://rps.com/api/games/{gameId}" "http://rps.com/api/games{?player1,player2}"
application/vnd.hal+json Minimalistic (plain old json)! "_links" with mandatory rels! "_embedded" (recursive!)
GET http://rps.com/api/games/123 <-- { ! ! ! ! ! ! ! ! ! ! ! ! ! ! "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" } hal+json
GET http://rps.com/api/games/123 <-- { ! ! ! ! ! ! ! ! "_links": { "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" } hal+json
GET http://rps.com/api/games/123 <-- { "_embedded": { "rps:player" : [{ "_links": { "self": {"href" : "http://rps.com/api/players/111"}, "name": "Jan" }, { "_links": { "self": {"href" : "http://rps.com/api/players/222"}, "name": "Cecilia" }] }, "_links": { "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" } hal+json
Application state, not objects GET http://rps.com/api/players/111/games/123 <-- { "_links": { "rps:game": {"href" : "http://rps.com/api/games/123"}, "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } }
GET http://rps.com/api/players/111/games/123 <-- { "_embedded": { "rps:game" : [{ "_links": { "self": {"href" : "http://rps.com/api/games/123"}, "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" }] }, "_links": { "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } } Application state, not objects
Summary Hypermedia simplifies client development! No constructing of URLs! Opportunities for less business logic! Pick a mediatype with reasonable semantics! Consider form-encoded when POSTing! Some useful tools! CURIE, URITemplates

More Related Content

PDF
Dealing with Azure Cosmos DB
byMihail Mateev
 
PDF
OSCamp #4 on Foreman | CLI tools with Foreman by Martin Bačovský
byNETWAYS
 
PPTX
Creating Truly RESTful APIs
byDomenic Denicola
 
ODP
Terms of endearment - the ElasticSearch Query DSL explained
byclintongormley
 
PPTX
Example-driven Web API Specification Discovery
byJavier Canovas
 
PDF
MongoDB user group israel May
byAlon Horev
 
PDF
[It]deft manuale full
bykirkblackberry
 
PDF
Trinity Kings World Leadership: The Law of Empowerment: Elders Are to Mentor ...
byTerrell Patillo
 
Dealing with Azure Cosmos DB
byMihail Mateev
 
OSCamp #4 on Foreman | CLI tools with Foreman by Martin Bačovský
byNETWAYS
 
Creating Truly RESTful APIs
byDomenic Denicola
 
Terms of endearment - the ElasticSearch Query DSL explained
byclintongormley
 
Example-driven Web API Specification Discovery
byJavier Canovas
 
MongoDB user group israel May
byAlon Horev
 
[It]deft manuale full
bykirkblackberry
 
Trinity Kings World Leadership: The Law of Empowerment: Elders Are to Mentor ...
byTerrell Patillo
 

Viewers also liked

PPSX
Watercolors. Acuarelas (Steve Hanks)
byCachi Chien
 
PPS
Mito.Myth.
byCachi Chien
 
PPSX
DESERT. George Corominas (2)
byCachi Chien
 
PPT
Intd
byRafael Rivera
 
PPTX
Git hacking
byChris Maury
 
PPTX
Imagination
byCachi Chien
 
PPTX
About Sacramento Real Estate
byDavid Yaffee
 
PPT
Linked In2
bysilverstard
 
PDF
Armed with Tools
byBaynote
 
PPS
絕美冰域 南極
byteresafeng
 
PPS
Iguazu Falls1
byNY13itch
 
PPTX
College Marketing Best Practices - Cory 2013
byCory Earl
 
Watercolors. Acuarelas (Steve Hanks)
byCachi Chien
 
Mito.Myth.
byCachi Chien
 
DESERT. George Corominas (2)
byCachi Chien
 
Intd
byRafael Rivera
 
Git hacking
byChris Maury
 
Imagination
byCachi Chien
 
About Sacramento Real Estate
byDavid Yaffee
 
Linked In2
bysilverstard
 
Armed with Tools
byBaynote
 
絕美冰域 南極
byteresafeng
 
Iguazu Falls1
byNY13itch
 
College Marketing Best Practices - Cory 2013
byCory Earl
 

Similar to Hypermedia APIs - GeekOut

PDF
Facebook & Twitter API
byFabrice Delhoste
 
PPTX
rest-api-basics.pptx
byAgungSutikno1
 
PPTX
rest-api-basics.pptx
byFikiRieza2
 
PDF
Rest web services
byPaulo Gandra de Sousa
 
PDF
REST APIS web development for backend familiarity
byARTUROGOMEZGARCIA2
 
PDF
Thinking restfully
byStelios Gorilas
 
PDF
Five API Styles
byronniemitra
 
PDF
Together Cheerfully to Walk with Hypermedia
byVladimir Tsukur
 
PDF
Hypermedia APIs and HATEOAS / Wix Engineering
byVladimir Tsukur
 
PDF
იოსებ ძმანაშვილი - The Web APIs
byunihack
 
PDF
Play! with rest
byGregor Trefs
 
PPTX
Tutorial_Rest_API_For_Beginners_125.pptx
byT.Choithram & Sons Dubai
 
PDF
WebApp #3 : API
byJean Michel
 
PDF
Doing REST Right
byKerry Buckley
 
PDF
RESTful applications: The why and how by Maikel Mardjan
byJexia
 
PPTX
REST Methodologies
byjrodbx
 
PPTX
Rest Essentials
bySergey Podolsky
 
PPTX
RESTful APIs
byAdi Challa
 
PPTX
RESTful Services
byJason Gerard
 
PPTX
Rest APIs Training
byShekhar Kumar
 
Facebook & Twitter API
byFabrice Delhoste
 
rest-api-basics.pptx
byAgungSutikno1
 
rest-api-basics.pptx
byFikiRieza2
 
Rest web services
byPaulo Gandra de Sousa
 
REST APIS web development for backend familiarity
byARTUROGOMEZGARCIA2
 
Thinking restfully
byStelios Gorilas
 
Five API Styles
byronniemitra
 
Together Cheerfully to Walk with Hypermedia
byVladimir Tsukur
 
Hypermedia APIs and HATEOAS / Wix Engineering
byVladimir Tsukur
 
იოსებ ძმანაშვილი - The Web APIs
byunihack
 
Play! with rest
byGregor Trefs
 
Tutorial_Rest_API_For_Beginners_125.pptx
byT.Choithram & Sons Dubai
 
WebApp #3 : API
byJean Michel
 
Doing REST Right
byKerry Buckley
 
RESTful applications: The why and how by Maikel Mardjan
byJexia
 
REST Methodologies
byjrodbx
 
Rest Essentials
bySergey Podolsky
 
RESTful APIs
byAdi Challa
 
RESTful Services
byJason Gerard
 
Rest APIs Training
byShekhar Kumar
 

Recently uploaded

PDF
Alluxio Webinar | Alluxio + S3 A Tiered Architecture for Latency-Critical, Se...
byAlluxio, Inc.
 
PPTX
Digital Twins for RolandRust U Maryland 20251030 v14.pptx
byhome
 
PDF
HTML_Final notes_with_header_and_footer.pdf
byJaydeep Kale
 
PDF
ESUG 2009: [Project planning], by Tim Mackinnon
byESUG
 
PDF
Workshop about mORMot 2 during EKON: write a clean-architecture TDD sample
byArnaud Bouchez
 
PDF
Working with Machine Learning in Production
byFrederick Apina
 
PDF
Comprehensive Guide to Performance Testing Tools and Services
byKanika Vatsyayan
 
PDF
Build Web, Mobile & Desktop Apps with Flutter
byShiv Technolabs Pvt. Ltd.
 
PDF
Cloud Migration Strategies using Oracle Cloud Infrastructure (OCI)
bymukeshnegi46
 
PDF
Hiring Dedicated Laravel Developers: Cost Breakdown
byShiv Technolabs Pvt. Ltd.
 
PDF
Choosing the Ideal iOS App Development Partner for Success
byShiv Technolabs Pvt. Ltd.
 
PDF
product realizatio n software.pdf
byJames Cameron
 
PPTX
B2B Marketing Attribution Solutions - VALiNTRY360
byVALiNTRY360
 
PDF
Insurance Underwriting Software for Smarter Operations
byInsurance Tech Services
 
PDF
How to Choose the Right Partner for Mobile App Development in the Philippines_.
byTechBuilder
 
PPTX
power point presentation of Soft computing
byyashhjain24
 
PPTX
Streamline Compliance and Safety with Advanced Contractor Management Software
bySHEQ Network Limited
 
PDF
VADY GenAI Dashboards: From KPIs to Executive-Ready Decisions in Seconds
byNewFangledVision
 
PDF
Incident Response Planning and Management
byCyberneticGI
 
PPTX
Hall-Pass-Management-Software-Transforming-School-Safety-and-Efficiency.pptx
byinfoswipesolutionsin
 
Alluxio Webinar | Alluxio + S3 A Tiered Architecture for Latency-Critical, Se...
byAlluxio, Inc.
 
Digital Twins for RolandRust U Maryland 20251030 v14.pptx
byhome
 
HTML_Final notes_with_header_and_footer.pdf
byJaydeep Kale
 
ESUG 2009: [Project planning], by Tim Mackinnon
byESUG
 
Workshop about mORMot 2 during EKON: write a clean-architecture TDD sample
byArnaud Bouchez
 
Working with Machine Learning in Production
byFrederick Apina
 
Comprehensive Guide to Performance Testing Tools and Services
byKanika Vatsyayan
 
Build Web, Mobile & Desktop Apps with Flutter
byShiv Technolabs Pvt. Ltd.
 
Cloud Migration Strategies using Oracle Cloud Infrastructure (OCI)
bymukeshnegi46
 
Hiring Dedicated Laravel Developers: Cost Breakdown
byShiv Technolabs Pvt. Ltd.
 
Choosing the Ideal iOS App Development Partner for Success
byShiv Technolabs Pvt. Ltd.
 
product realizatio n software.pdf
byJames Cameron
 
B2B Marketing Attribution Solutions - VALiNTRY360
byVALiNTRY360
 
Insurance Underwriting Software for Smarter Operations
byInsurance Tech Services
 
How to Choose the Right Partner for Mobile App Development in the Philippines_.
byTechBuilder
 
power point presentation of Soft computing
byyashhjain24
 
Streamline Compliance and Safety with Advanced Contractor Management Software
bySHEQ Network Limited
 
VADY GenAI Dashboards: From KPIs to Executive-Ready Decisions in Seconds
byNewFangledVision
 
Incident Response Planning and Management
byCyberneticGI
 
Hall-Pass-Management-Software-Transforming-School-Safety-and-Efficiency.pptx
byinfoswipesolutionsin
 

Hypermedia APIs - GeekOut

  • 1.
  • 2.
    Hypermedia API:s @Jayway Rickard Öberg (~2010)! Qi4j & Streamflow! Usecases as your API! Mattias Arthursson & Karl-Johan Stenflo (~2011)! JAX-RS-HATEOAS! HATEOAS with Standard Java APIs! Mads Enevoldsen & Jan Kronquist (~2011)! Forest (CQS conventions, sensible default links, constraints...)! Gustaf Nilsson Kotte (~2012)! Adaptive HTML as your API
  • 3.
    Outline Example domain! REST introduction(Richardson maturity model)! Exploring media types! html! collection+json! hal+json
  • 4.
  • 5.
    Rock - Paper- Scissors
  • 6.
  • 7.
  • 8.
    http://rps.com The future Facebookof Rock Paper Scissors! Millions of users! Many games per user
  • 9.
    Playing the game PlayerA Player B Server rock paper Player B: paper Player A: rock Game 123 Game 123 winner: Player B loser: Player A CREATED WAITING GAME WON GAME TIED any move other move (victory) other move (tie) T
  • 10.
  • 11.
    Towards REST REST architecturalstyle! Defined by Roy Fielding ! Richardson maturity model http://martinfowler.com/articles/richardsonMaturityModel.html
  • 12.
    Level 0 -Not at all RESTful Single resource, single verb! Examples:! SOAP, XML-RPC, JSON-RPC
  • 13.
    Level 0 -Example POST /api --> { "method": “viewGame", "params": ["123"]} <-- { "result": { "state": "waiting"}, "error": null} POST /api --> { "method": "makeMove", "params": ["123","rock"]} <-- { "result": { "state": "won", "winner": "player1", "loser": "player2"}, "error": null}
  • 14.
    Level 0 -Analysis HTTP as transport protocol! Problems! No client side caching! Tight coupling
  • 15.
    Level 0 -In the wild JSON/RPC over HTTP! Why?! Simplicity! Track all user actions! If it ain’t broke, don't fix it
  • 16.
    Level 1 -Resources Many resources, single verb! /api/games/123 /api/players/player1 Almost “object oriented”
  • 17.
    Level 1 -Example POST /api/games/123 --> { "method": "viewGame"} <-- { "result": { "state": "waiting"}, "error": null} POST /api/games/123 --> { "method": "makeMove", "params": ["rock"]} <-- { "result": { "state": "won", "winner": "player1", "loser": "player2"}, "error": null}
  • 18.
    Level 1 -Analysis Still just using HTTP as transport
  • 19.
    Level 2 -Verbs Resources, verb and status codes!! GET, POST, PUT, DELETE... 200 OK, 304 Not Modified, 404 Not found… RESTish! Uniform interface
  • 20.
    HTTP 101 GET -safe! POST - danger!! PUT - idempotent! ! Note! GET will not modify the resource, but other clients might! Interleaving other requests might break idempotency
  • 21.
    GET /api/games/123 <-- 200OK <-- { "state": "waiting"} POST /api/games/123 --> { "move": "rock"} <-- 200 OK <-- { "state": "won", "winner": "player1", "loser": “player2"} Level 2 - Example
  • 22.
    GET /api/games/123 <-- 200OK <-- { "state": "waiting"} POST /api/games/123 --> Content-Type: application/json --> { "move": "rock"} <-- 200 OK <-- { "state": "won", "winner": "player1", "loser": "player2"} Level 2 - Mediatype json
  • 23.
    Level 2 -Mediatype form GET /api/games/123 <-- 200 OK <-- { "state": "waiting"} POST /api/games/123 --> Content-Type: application/x-www-form-urlencoded --> move=rock <-- 200 OK <-- { "state": "won", "winner": "player1", "loser": "player2"} $ curl -d move=rock http://rps.com/api/games/123
  • 24.
    Level 2 -In the wild Verbs: GET, DELETE, PUT! Resources: buckets, objects, acls, policies…! Why?! CRUD operations! GET allows caching
  • 25.
    Level 2 -Analysis Using HTTP, not fighting it! Problems! Client must construct URLs! Client must contain business rules
  • 26.
    GET /api/games <-- 200OK <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "items": [{"id": "111", "players": ["jan", "cecilia"]}, {"id": "222", "players": ["jan", "mike"]}, {"id": "333", "players": ["cecilia", "mike"]}, ...]} Level 2 - Constructing URLs GET /api/games?offset=10 GET /api/games?page=2 How to navigate to page 2?
  • 27.
    GET /api/games <-- 200OK <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "items": [{"id": "111", "players": ["jan", "cecilia"]}, {"id": "222", "players": ["jan", "mike"]}, {"id": "333", "players": ["cecilia", "mike"]}, ...]} Level 2 - Constructing URLs GET /api/games/{game.id} Navigating to game
  • 28.
    Level 2 -Business logic GET /api/games/123 <-- 200 OK <-- { "state": "waiting", "players": ["ply1", "ply2"], "moves": { "ply1" : true} } Should the client display the move selector?
  • 29.
    Level 2 -Business logic solved? GET /api/games/123 <-- 200 OK <-- { "state": "waiting", "players": ["ply1", "ply2"], "moves": { "ply1" : true}, "shouldMove": true }
  • 30.
    Level 3 -Hypermedia Controls Links & forms! REST as defined by Roy Fielding Hypermedia is defined by the presence of application control information embedded within, ! or as a layer above, the presentation of information The simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions.
  • 31.
    GET /api/games <-- 200OK <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "next": "/api/games?offset=10", "items": [{"href": "/api/games/111", "players": ["jan", "cecilia"]}, {"href": "/api/games/222", "players": ["jan", "mike"]}, {"href": "/api/games/333" "players": ["cecilia", "mike"]}, ...]} Level 3 - Example (links)
  • 32.
    Level 3 -Example (form) <html> <body> <ol id="players"> <li>Jan</li> <li>Cecilia</li> </ol> <form action="/api/games/111" method="POST"> <select name="move"> <option value="rock">Rock</option> <option value="paper">Paper</option> <option value="scissors">Scissors</option> </select> <input type="submit"/> </form> </body> </html>
  • 33.
    Level 3 -Opportunity: Extra moves <select name="move"> <option value="rock">Rock</option> <option value="paper">Paper</option> <option value="scissors">Scissors</option> <option value="lizard">Lizard</option> <option value="spock">Spock</option> </select>
  • 34.
    Level 3 -Changing the rules For one of the players: Flip a coin! head - he must play rock! tail - he can play whatever he wants! ! How can the other player take advantage of this? http://blog.gtorangebuilder.com/2014/04/gto-brain-teaser-1-exploitation-and.html <select name="move"> <option value="rock">Rock</option> </select>
  • 35.
    Level 3 -In the wild
  • 36.
  • 37.
    Media types Format! application/json, text/xml,text/plain, text/csv! Domain specific! text/vcard, text/calendar, application/calendar+json! Hypermedia! text/html, application/xhtml+xml! application/vnd.collection+json, application/vnd.hal+json! application/vnd.siren+json, application/vnd.amundsen-uber+json
  • 38.
    GET /api/games <-- 200OK <-- Content-Type: application/json <-- { "totalCount": 23, "offset": 0, "pageSize": 10, "next": "/api/games?offset=10", ... } json
  • 39.
    xhtml GET /api/games <-- 200OK <-- Content-Type: application/xhtml+xml <-- <html> <body> <a href="/api/games?offset=10">Next</a> <div id="totalCount">23</div> <ol id="games"> <li>...</li> <li>...</li> </ol> </body> </html>
  • 40.
    collection+json CRUD for collectionsof objects! Parts of the document:! items! links! queries! templates! errors
  • 41.
    GET /api/games <-- 200OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games", "links" : [ {"rel" : "next", "href" : "/api/games?offset=10"} ], "items" : [ { ... }, { ... } ] } } collection+json
  • 42.
    Anatomy of aLink target url (href)! human readable string (title)! semantic information (rel)! returned media types (type)! ! http method (method)! secondary key (name)! support media types for requests (accept) RFC 5988
  • 43.
  • 44.
    Custom rels Register withIANA :-)! Just make up your own :-)! move! URI! http://rps.com/rels/move! CURIE! rps:move! http://rps.com/rels/{rel}
  • 45.
    Forms / templates Morethan links! Allow user input! May provide! Default values! Data types! Possible values
  • 46.
    html form <html> <body> <ol id="players"> <li>Jan</li> <li>Cecilia</li> </ol> <formaction="/api/games/111" method=“POST" name="move"> <select name="move"> <option value="rock">Rock</option> <option value="paper">Paper</option> <option value="scissors">Scissors</option> </select> <input type="submit"/> </form> </body> </html>
  • 47.
    GET /api/games/111 <-- 200OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games/111", "template" : { "data" : [{ "name" : "move", "value" : "", "prompt" : "Your move" }] } } } collection+json template for writes
  • 48.
    Forced resource structure Collection ofgames /api/games/ Game 111 /api/games/111 Collection of moves for game 111 /api/games/111/moves Player 1 move for game 111 /api/games/111/moves/ply1 item rps:moves item
  • 49.
    GET /api/games/111 <-- 200OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games/111", "links" : [ {"rel" : "rps:moves", "href" : "/api/games/111/moves"} ], ... } } The game links to moves
  • 50.
    GET /api/games/111/moves <-- 200OK <-- Content-Type: application/vnd.collection+json <-- { "collection": { "version" : "1.0", "href" : "http://rps.com/api/games/111/moves", "template" : { "data" : { "name" : "move", "value" : "", "prompt" : "Your move" } } } } moves collection contain template
  • 51.
    URI templates Constructing paths
 
 Form-style! Makinga move
 
 Creating a new game RFC 6570 "http://rps.com/api/games/111{?move}" "http://rps.com/api/games/{gameId}" "http://rps.com/api/games{?player1,player2}"
  • 52.
    application/vnd.hal+json Minimalistic (plain oldjson)! "_links" with mandatory rels! "_embedded" (recursive!)
  • 53.
  • 54.
    GET http://rps.com/api/games/123 <-- { ! ! ! ! ! ! ! ! "_links":{ "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" } hal+json
  • 55.
    GET http://rps.com/api/games/123 <-- {"_embedded": { "rps:player" : [{ "_links": { "self": {"href" : "http://rps.com/api/players/111"}, "name": "Jan" }, { "_links": { "self": {"href" : "http://rps.com/api/players/222"}, "name": "Cecilia" }] }, "_links": { "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" } hal+json
  • 56.
    Application state, notobjects GET http://rps.com/api/players/111/games/123 <-- { "_links": { "rps:game": {"href" : "http://rps.com/api/games/123"}, "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } }
  • 57.
    GET http://rps.com/api/players/111/games/123 <-- {"_embedded": { "rps:game" : [{ "_links": { "self": {"href" : "http://rps.com/api/games/123"}, "createdAt" : "2014-05-22T16:24:01", "state" : "waiting" }] }, "_links": { "rps:move": { "href": "http://rps.com/api/games/123{?move}", "templated": true } } } Application state, not objects
  • 58.
    Summary Hypermedia simplifies clientdevelopment! No constructing of URLs! Opportunities for less business logic! Pick a mediatype with reasonable semantics! Consider form-encoded when POSTing! Some useful tools! CURIE, URITemplates