A keynote from APIdays, Dec 3-4 2012, Paris, France that covers an analytical & practical approach towards designing APIs in general, and hypermedia in specific, as outlined by an experience at Klarna, Sweden. Questions? http://twitter.com/andreineculau Higher quality slides at: https://speakerdeck.com/andreineculau/rpc-to-rest-hypermedia

2. RPC to Hypermedia
REST
Concrete case on Payments API
@andreineculau

3. RPC - Making a Remote Procedure Call
1 client imagines :
2 server . translate ’ Hello ’ , ’sv ’
3
4
5 client sends :
6 POST / rpc
7 Content - Type : application / json
8 {
9 method : translate ,
10 args : [ Hello , sv ]
11 }
1 server expects :
2 app . post ’/ rpc ’ , ( req , res ) -
3 fun = req . body . method # translate
4 args = req . body . args # Hello , sv
5 call fun , args # Hej
6
7
8 server sends :
9 200 OK
10 Content - Type : application / json
11 {
12 result : Hej
13 }

4. REST - Making a HTTP request
1 client imagines :
2 server . translate ’ Hello ’ , ’sv ’
3
4
5 client sends :
6 POST / translate
7 Content - Type : application / json
8 {
9 text : Hello ,
10 language : sv
11 }
1 server expects :
2 app . post ’/ translate ’ , ( req , res ) -
3 fun = ’ translate ’ # translate
4 args = req . body # Hello , sv
5 call fun , args # Hej
6
7
8 server sends :
9 200 OK
10 Content - Type : application / json
11 {
12 result : Hej
13 }

5. RPC to REST

6. RPC to REST

7. RPC to REST

8. Look around you. It’s not just you.

9. Perspectives. Hypermedia vs REST

10. Klarna

11. Journey of an API
envision
spec
mock
serve
consume

12. Serving uniform HTTP

13. serve: Webmachine

14. serve: JeSSE
schema

16. Journey of an API
envision
spec
mock
serve
consume

17. envision: RESTgraph

18. spec: RESTpi for machines

19. spec: RESTpi by humans for humans

20. mock: Apiary.io

21. consume: RESTit
1 URI as the only runtime requirement
Centered around resources
Simplify representations
Transfer Protocol Layer
Hypermedia Layer
Hooks
Sugar

22. consume: RESTit
1 it ’ should enter the store and look around ’ , ( done ) -
2 re$ = RESTit (). re$
3 re$ ( ’ http :// starbucks . apiary . io ’)
4 . read ()
5 . callback ( err , resp ) -
6 return done err if err
7 resp [0]. statusCode . should . equal 200
8 done ()
1 it ’ should see what can be done with orders ’ , ( done ) -
2 re$ = RESTit (). re$
3
4 re$ ( ’ http :// starbucks . apiary . io ’)
5 . read ()
6 . follow ( ’/ rels / orders ’)
7 . options ()
8 . callback ( err , resp ) -
9 return done err if err
10 resp [0]. statusCode . should . equal 200
11 resp [0]. canPOST . should . equal true
12 should . not . equal resp [0]. canDELETE , true # undefined
13 done ()

23. consume: RESTit
1 it ’ should place an order and then update it ’ , ( done ) -
2 re$ = RESTit (). re$
3
4 re$ ( ’ http :// starbucks . apiary . io ’)
5 . read ()
6 . follow ( ’/ rels / orders ’)
7 . create ({ representation :{ drink : ’ espresso ’}})
8 . fo llowLocation ()
9 . read ()
10 . callback ( err , resp ) -
11 return done err if err
12 resp [0]. statusCode . should . equal 200
13 @ [0]. bookmarkAs ’ myOrder ’
14 changeMyMind ()
15
16 changeMyMind = () -
17 re$ ( ’ myOrder ’)
18 . update ({ representation :{ ammend_drink : ’ with cream ’}})
19 . callback ( err , resp ) -
20 return done err if err
21 return done ()
22 resp [0]. statusCode . should . equal 200
23 resp [0]. representation . get ( ’. drink ’). should . equal ’ espresso con panna ’
24 done ()

24. consume: RESTit
1 it ’ should smuggle an order ’ , ( done ) -
2 re$ = RESTit (). re$
3
4 re$ ( ’ myOrder ’)
5 . go ( ’ smuggle ’ , { representation :{ drink : ’ latte ’}})
6 . callback ( err , resp ) -
7 return done err if err
8 resp [0]. statusCode . should . equal 200
9 resp [0]. representation . get ( ’. drink ’). should . equal ’ latte ’
10 done ()

25. tools
simpler, safer more fun

26. KITT
KISS

27. RPC to Hypermedia
REST
Concrete case on Payments API
@andreineculau
December 3-4, 2012, APIdays.io

28. Credits
Scott Brinker, Marketing Technology Landscape Supergraphic
Adam DuVander/Programmable Web, 5000 APIs: Facebook, Google, Twitter are changing the
web
Google Trends: Architecture styles
Simon Dongle, Good Morning 2012
Alan Dean, HTTP/1.1 activity diagram
Philipp Meier, Liberator
Data-Driven Documents
sigma.js