REST: From GET to HATEOAS or how to create RESTful APIs 2 - - PowerPoint PPT Presentation

▶
rest from get to hateoas
SMART_READER_LITE
LIVE PREVIEW

REST: From GET to HATEOAS or how to create RESTful APIs 2 - - PowerPoint PPT Presentation

Oct 06, 2023 401 likes •943 views

JPoint REST: From GET to HATEOAS or how to create RESTful APIs 2 Who am I? ~ just some java guy ~ Jos Dirksen Interests Books Architect @ JPoint Java &

slide-1
SLIDE 1

JPoint ¡ … ¡or ¡how ¡to ¡create ¡RESTful ¡APIs ¡

REST: From GET to HATEOAS

slide-2
SLIDE 2

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

2 Architect ¡@ ¡JPoint ¡

  • Live ¡in ¡Waalwijk ¡
  • Married ¡
  • Daughter ¡(2.5 ¡y/o) ¡
  • Blog ¡at: ¡

www.smartjava.org ¡

  • Java ¡& ¡Scala ¡
  • REST, ¡WS-­‑* ¡
  • HTML5 ¡

¡

  • Snowboarding ¡
  • Reading ¡
  • Cooking ¡

Shameless ¡self ¡promotion: ¡

  • SOA ¡Governance ¡in ¡

Action, ¡Manning, ¡2012 ¡

  • Open ¡Source ¡ESBs ¡in ¡

Action, ¡Manning, ¡2008 ¡

~ ¡just ¡some ¡java ¡guy ¡~ ¡

Who am I?

Jos Dirksen Interests Books

slide-3
SLIDE 3

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

3

~ ¡you ¡will ¡encounter ¡opinionated ¡content ¡~ ¡

Disclaimer

Heavily opinionated

  • There are many truths
  • This is mine
  • I’m not a Restafarian
slide-4
SLIDE 4

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

4

~ ¡It ¡was ¡a ¡dark ¡place ¡~ ¡

In the beginning…

slide-5
SLIDE 5

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

5

Many different ‘standards’:

RMI, ¡SOAP, ¡Corba, ¡DCE, ¡DCOM ¡

From many different parties:

Sun, ¡Microsoft, ¡IBM, ¡OASIS, ¡OMG ¡

Caused many problems:

  • Bad ¡interoperability. ¡
  • Reinvent ¡the ¡wheel. ¡
  • Vendor ¡‘lock-­‑in’. ¡

The world before REST!

slide-6
SLIDE 6

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

6

And then came REST!

“Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web”

slide-7
SLIDE 7

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

7

~ ¡Rest ¡101 ¡~ ¡

REST is based on a set of constraints

  • 4. Uniform interface

There is a uniform interface between clients and servers.

  • 5. Layered System

Must allow concepts such as load balancers, proxies and firewalls.

  • 6. Code-On-Demand (optional)

Client can request code from server and execute it.

  • 1. Client-server

Separate clients and servers.

  • 2. Stateless server

Each request from a client contains all the information necessary to service the request.

  • 3. Cacheable

Clients can cache responses, responses must indicate if this is allowed.

slide-8
SLIDE 8

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

8

~ ¡Rest ¡101 ¡~ ¡

Constraint 4: Uniform interface

A. Identification of resources:

E.g. by using an URI.

B. Manipulation of resources through representations:

A representations allows user to modify/delete resource .

C. Self-descriptive messages:

Process message based on message and meta-data.

D. Hypermedia as the engine of application state:

State transitions are defined in representations.

slide-9
SLIDE 9

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

9

Why do this? Why be RESTful?

  • Scalable
  • Fault-tolerant
  • Recoverable
  • Secure
  • Loosely coupled

And all was good!

“Exactly what we want in the applications we are developing!”

slide-10
SLIDE 10

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

10

But not everybody understood…

  • GET: /getAllDogs
  • GET: /saveDog?name=brian&age=7
  • GET: /feedDog?food=123&dog=brian

instead of:

  • GET: /dogs
  • PUT: /dog/brian
  • POST: /dog/brian/food/123

“In your URLs – nouns are good; verbs are (usually) bad”

slide-11
SLIDE 11

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

Bad URLs:

  • POST statuses/destroy/:id
  • GET statuses/show/:id
  • POST direct_messages/new

Instead of:

  • DELETE status/:id
  • GET status/:id
  • POST direct_message or PUT direct_message/:id

11

~ ¡just ¡saying ¡your ¡RESTful ¡doesn’t ¡make ¡it ¡so ¡~ ¡

Twitter API

slide-12
SLIDE 12

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

12

The maturity levels of REST

slide-13
SLIDE 13

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

13

Richardson’s Maturity Model

slide-14
SLIDE 14

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

14

~ ¡nothing ¡to ¡do ¡with ¡REST ¡~ ¡

Level 0: The Swamp of Pox

  • One URI, one HTTP method
  • XML-RPC / SOAP / POX
  • Giant ‘black box’, is what eBay uses.

POST /appointmentService HTTP/1.1 [various other headers] <appointmentRequest> <slot doctor = "mjones" start = "1400" end = "1450"/> <patient id = "jsmith"/> </appointmentRequest>

slide-15
SLIDE 15

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

15

~ ¡not ¡an ¡easy ¡to ¡use ¡API ¡~ ¡

Level 0: eBay

POST http://svcs.ebay.com/services/search/FindingService/v1 <findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/ search/v1/services"> <affiliate> <networkId>9</networkId> <trackingId>1234567890</trackingId> <customId>k-man</customId> </affiliate> <sortOrder>EndTime</sortOrder> <paginationInput> <entriesPerPage>2</entriesPerPage> </paginationInput> <keywords>camalots</keywords> </findItemsByKeywordsRequest>

slide-16
SLIDE 16

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

16

~ ¡lots ¡of ¡APIs ¡start ¡out ¡this ¡way ¡~ ¡

Level 1: Resources

  • Each resource has an unique URI
  • Single HTTP verb (usually POST or GET)
  • Verbs have no meaning, used to tunnel over HTTP
  • Early versions of Flickr, del.ico.us and Amazon

POST /slots/1234 HTTP/1.1 [various other headers] <appointmentRequest> <patient id = "jsmith"/> </appointmentRequest>

slide-17
SLIDE 17

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

17

~ ¡close ¡but ¡no ¡sigar ¡~ ¡

Level 2: HTTP Verbs

  • Many URIs, using multiple verbs
  • Correct use of response codes
  • Exposes state, not behavior
  • Crud services, can be useful e.g Amazon S3

GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Host: royalhope.nhs.uk HTTP/1.1 200 OK <openSlotList> <slot id = "1234” start = "1400" end = "1450"/> <slot id = "5678” start = "1600" end = "1650"/> </openSlotList>

slide-18
SLIDE 18

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

18

~ ¡True ¡RESTful ¡~ ¡

Level 3: Hypermedia controls

  • Resources are self-describing
  • Hypermedia As The Engine Of Application State (HATEOAS)
  • Exposes state and behavior

<appointment> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/> <patient id = "jsmith"/> <link rel = "/linkrels/appointment/addTest" uri = "/slots/1234/appointment/tests"/> <link rel = "/linkrels/appointment/updateContactInfo" uri = "/patients/jsmith/contactInfo"/> </appointment>

slide-19
SLIDE 19

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

19

So, are level 0, 1 and 2 RESTful?

“What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine

  • f application state (and hence the API) is not being driven by

hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?” Roy T. Fielding

slide-20
SLIDE 20

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

20

~ ¡Worst ¡acronym ¡ever! ¡~ ¡

Level 2 is easy, how do we do HATEOAS?

slide-21
SLIDE 21

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

21

HATEOAS?

“The next control state of an application resides in the representation of the first requested resource, … The application state is controlled and stored by the user agent … anticipate changes to that state (e.g., link maps and prefetching of representations) … The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations.” Roy T. Fielding

slide-22
SLIDE 22

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

22

Say what?

slide-23
SLIDE 23

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

23

The key to HATEOAS is simple

  • Hypermedia / Mime-types / Media-types :
  • Describes a current state
  • Compare it with a web page
  • Can be seen as the contract
  • Links:
  • Describe the transition to the next state
  • Compare it with hyperlinks
  • HATEOAS makes surfing the web possible
  • Jim Webber: “Hypermedia Describes Protocols” (HYDEPR)

“In each response message, include the links for the next request message”

slide-24
SLIDE 24

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

24

~ ¡AtomPub ¡~ ¡

HATEOAS Part 1: Links

<feed xmlns="http://www.w3.org/2005/Atom"> <title>Example Feed</title> <subtitle>A subtitle.</subtitle> <link href="http://example.org/feed/" rel="self" /> <link href="http://example.org/" /> <id>urn:uuid:60a76c80-d399-11d9-b91C-0003939e0af6</id> <updated>2003-12-13T18:30:02Z</updated> <author> <name>John Doe</name> <email>johndoe@example.com</email> </author> <entry> <title>Atom-Powered Robots Run Amok</title> <link href="http://example.org/2003/12/13/atom03" /> <link rel="alternate" type="text/html" href="http://example.org/2003/12/13/atom03.html"/>

slide-25
SLIDE 25

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

25

~ ¡NetGlix ¡API ¡~ ¡

HATEOAS Part 1: Links

<link href href="http://.../ ="http://.../catalog catalog/titles titles/series/70023522/cast” /series/70023522/cast” rel="http:// rel="http://schemas.netflix.com schemas.netflix.com/catalog catalog/people people" " title title="cast"> ="cast"> <cast> <link <link href href="http:// ="http://api.netflix.com api.netflix.com/catalog catalog/people people/30011713" /30011713" rel="http:// rel="http://schemas.netflix.com schemas.netflix.com/catalog catalog/person" /person" title title="Steve ="Steve Carell Carell"/> "/> <link <link href href="http:// ="http://api.netflix.com api.netflix.com/catalog catalog/people people/30014922" /30014922" rel="http:// rel="http://schemas.netflix.com schemas.netflix.com/catalog catalog/person" /person" title title="John ="John Krasinski Krasinski"/> "/> <link <link href href="http:// ="http://api.netflix.com api.netflix.com/catalog catalog/people people/20047634" /20047634" rel="http:// rel="http://schemas.netflix.com schemas.netflix.com/catalog catalog/person" /person" title title=" ="Jenna Jenna Fischer"/> Fischer"/> </cast> </link>

slide-26
SLIDE 26

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

26

~ ¡Before ¡using ¡links~ ¡

HATEOAS Part 1: Twitter Example

GET .../followers/ids.json?cursor=-1&screen_name=josdirksen { “previous_cursor”: 0, “previous_cursor_str”: 0, “ “ids ids”: [ ”: [ 12345678, 12345678, 87654321, 87654321, 11223344 11223344 ], ], “next_cursor”: 0, “next_cursor_str”: “0” }

slide-27
SLIDE 27

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

27

~ ¡With ¡links~ ¡

HATEOAS Part 1: Twitter Example

GET .../followers/ids.json?cursor=-1&screen_name=josdirksen { “previous_cursor”: 0, “id”: { “name”: “John Smit”, “id”: “12345678” “links” : [ “links” : [ { “rel”: “User info”, { “rel”: “User info”, “ “href href”: “ ”: “https https://.../user/12345678”}, ://.../user/12345678”}, { “rel”: “Follow user”, { “rel”: “Follow user”, “ “href href”: “ ”: “https https://.../ ://.../friendship friendship/12345678”} /12345678”} ] ] } // and add other links: tweet to, send direct message, ..// block, report for spam, add or remove from list }

slide-28
SLIDE 28

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

28

HATEOAS Part 2: Media-types

WHERE: HOW: WHAT:

People ¡know ¡where ¡to ¡`ind ¡your ¡ resource ¡using ¡URIs. ¡ They ¡know ¡how ¡to ¡interact ¡by ¡ following ¡links. ¡ But ¡what ¡do ¡the ¡resources ¡look ¡ like, ¡what ¡do ¡they ¡need ¡to ¡post? ¡

slide-29
SLIDE 29

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

29

HATEOAS Part 2: Media-types

~ ¡not ¡all ¡media-­‑types ¡are ¡equal, ¡some ¡are ¡more ¡equal ¡than ¡others ¡~ ¡

  • Standard formats
  • Easy to use and understand.
  • Clients already know how to use them
  • Don’t always match with what you want to do
  • XHTML and AtomPub
  • Self created
  • Very domain specific
  • Can have rich semantics
  • Client specific implementation required
  • Often described using XML Schema
  • r in plain text, or not at all…
slide-30
SLIDE 30

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

30

HATEOAS Part 2: Media-types

~ ¡Custom ¡media ¡types ¡~ ¡

200 OK Content-Type: application/vnd.bank.org.account+xml;charset=UTF-8

  • <accounts xmlns="urn:org:bank:accounts">

<account> <id>AZA12093</id> <link href="http://bank.org/account/AZA12093" rel="self"/> <link rel="http://bank.org/rel/transfer" type="application/vnd.bank.org.transfer+xml" href="http://bank.org/transfers"/> <link rel="http://bank.org/rel/customer" type="application/vnd.bank.org.customer+xml" href="http://bank.org/customer/7t676323a"/> <balance currency="USD">993.95</balance> </account> </accounts>

slide-31
SLIDE 31

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

31

And that is what HATEOAS means!

  • Media-types describe the resources.
  • Actions are executed by following links.
  • Each new response reflects a state.
  • It is good to create custom media-types.
  • Creates self-describing APIs.
  • Clients ‘explore’ your API just as they browse the web.

“Media-types describes a domain specific application protocol”

slide-32
SLIDE 32

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

32

~ ¡With ¡links, ¡but ¡no ¡media-­‑type ¡~ ¡

HATEOAS Part 2: Twitter Example

GET .../followers/ids.json?cursor=-1&screen_name=josdirksen { “previous_cursor”: 0, “id”: { “name”: “John Smit”, “id”: “12345678” “links” : [ “links” : [ { “rel”: “User info”, { “rel”: “User info”, “ “href href”: “ ”: “https https://.../user/12345678”}, ://.../user/12345678”}, { “rel”: “Follow user”, { “rel”: “Follow user”, “ “href href”: “ ”: “https https://.../ ://.../friendship friendship/12345678”} /12345678”} ] ] } ... }

slide-33
SLIDE 33

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

33

~ ¡With ¡links ¡& ¡media-­‑type ¡~ ¡

HATEOAS Part 2: Twitter Example

GET .../followers/ids.json?cursor=-1&screen_name=josdirksen { “previous_cursor”: 0, “id”: { “name”: “John Smit”, “id”: “12345678” “links” : [ “links” : [ { “type: “ { “type: “application/ application/vnd.twitter.com.user vnd.twitter.com.user”, ”, “rel”: “User info”, “rel”: “User info”, “ “href href”: “ ”: “https https://.../user/12345678”}, ://.../user/12345678”}, { “type”: “ { “type”: “application/ application/vnd.twitter.com.user.follow vnd.twitter.com.user.follow”, ”, “rel”: “Follow user”, “rel”: “Follow user”, “ “href href”: “ ”: “https https://.../ ://.../friendship friendship/12345678”} /12345678”} ] ] // and add other options: tweet to, send direct message, // block, report for spam, add or remove from list } // This is how you create a self-describing API. }

slide-34
SLIDE 34

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

34

~ ¡API ¡should ¡guide ¡the ¡user ¡~ ¡

Case: eBay

Common scenario: bidding on item

  • 1. Add ¡item ¡to ¡watch ¡list: ¡keep ¡

track ¡of ¡the ¡item. ¡ ¡

  • 2. Get ¡user ¡details: ¡`ind ¡out ¡more ¡

about ¡the ¡buyer. ¡ ¡

  • 3. Get ¡user ¡feedback: ¡is ¡seller ¡

trustworthy? ¡ ¡

  • 4. Make ¡a ¡bid: ¡place ¡a ¡bid ¡for ¡the ¡
  • item. ¡
slide-35
SLIDE 35

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

35

~ ¡just ¡like ¡a ¡browser ¡does ¡using ¡links ¡~ ¡

eBay: API should help the client

slide-36
SLIDE 36

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

36

~ ¡API ¡should ¡tell ¡us ¡what ¡to ¡do ¡~ ¡

eBay: add to watchlist

GET .../item/180881974947 { “name” : “Monty Python and the Holy Grail white rabbit big pointy teeth”, “id” : “180881974947”, “start-price” : “6.50”, “currency” : “GBP”, ... “links” : [ { “type: “ { “type: “application/ application/vnd.ebay.item vnd.ebay.item”, ”, “rel”: “ “rel”: “Add Add item item to to watchlist watchlist”, ”, “ “href href”: “ ”: “https https://.../user/12345678/ ://.../user/12345678/watchlist watchlist/180881974947”}, /180881974947”}, { { // and a whole lot of other operations ] ] }

slide-37
SLIDE 37

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

37

~ ¡Follow ¡links ¡to ¡get ¡more ¡information ¡~ ¡

eBay: get user details

GET .../item/180881974947 { “name” : “Monty Python and the Holy Grail white rabbit big pointy teeth”, “id” : “180881974947”, “start-price” : “6.50”, “currency” : “GBP”, // whole lot of other general item data “bidder” : { “name” : “dangermouse_rm”, “link” : { “type” : “ “type” : “application/ application/vnd.ebay.user vnd.ebay.user”, ”, “rel : “Get user details”, “rel : “Get user details”, “ “href href : “ : “https https://.../user/314512346523” ://.../user/314512346523” } } }

slide-38
SLIDE 38

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

38

~ ¡Depending ¡on ¡rights ¡we ¡get ¡different ¡links ¡~ ¡

eBay: get user feedback

GET .../user/314512346523 { “name” : “dangermouse_rm”, “location” : “united kingdom”, // whole lot of other general user data “feedbacks” : { “last_month” : “7,0,0” “last_6_month” : “19,0,0”, “feedback” : { “title” : “Great communication and quick delivery. +++” “link” : { “type” : “ “type” : “application/ application/vnd.ebay.feedback vnd.ebay.feedback”, ”, “rel : “Show feedback”, “rel : “Show feedback”, “ “href href : “ : “https https://.../user/314512346523/feedback/1234567” ://.../user/314512346523/feedback/1234567” } ...

slide-39
SLIDE 39

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

39

~ ¡Depending ¡on ¡rights ¡we ¡get ¡different ¡links ¡~ ¡

eBay: place bid

GET .../item/180881974947 { “name” : “Monty Python and the Holy Grail white rabbit big pointy teeth”, “id” : “180881974947”, “start-price” : “6.50”, “currency” : “GBP”, ... “links” : [ { “type: “ { “type: “application/ application/vnd.ebay.bid vnd.ebay.bid”, ”, “rel”: “ “rel”: “Place Place bid”, bid”, “ “href href”: “ ”: “https https://.../user/12345678/bid/180881974947”}, ://.../user/12345678/bid/180881974947”}, { { // and a whole lot of other operations ] ] }

slide-40
SLIDE 40

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

40

~ ¡and ¡there ¡was ¡much ¡rejoicing ¡~ ¡

eBay: much easier!

slide-41
SLIDE 41

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

41

Versioning without breaking

slide-42
SLIDE 42

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

42

~ ¡Media-­‑types ¡~ ¡

Three options for versioning

  • Media-type is versioned, directly in its name

Request: GET /opengov/garbageschedule?location=Main%20Street HTTP/1.1 Accept: application/vnd.opengov.org.garbageschedule-v2+json Accept: application/vnd.opengov.org.garbageschedule-v2+json Response: HTTP/1.1 200 OK Content-Type: application/vnd.opengov.org.garbageschedule-v2+json application/vnd.opengov.org.garbageschedule-v2+json {"schedule" "self": "schedule-2423", "dayOfWeek": "Monday", "oddOrEvenWeeks": "Odd"}

slide-43
SLIDE 43

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

43

~ ¡Add ¡version ¡qualiGier ¡~ ¡

Three options for versioning

  • Media-type stays the same, add a qualifier.

Request: GET /opengov/garbageschedule?location=Main%20Street HTTP/1.1 Accept: application/ application/vnd.opengov.org.garbageschedule+json;v vnd.opengov.org.garbageschedule+json;v=1 =1 Response: HTTP/1.1 200 OK Content-Type: application/ application/vnd.opengov.org.garbageschedule+json;v vnd.opengov.org.garbageschedule+json;v=1 =1 {"schedule" "self": "schedule-2423", "dayOfWeek": "Monday", "oddOrEvenWeeks": "Odd"}

slide-44
SLIDE 44

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

44

~ ¡The ¡URI ¡is ¡versioned ¡~ ¡

Three options for versioning

  • The version is added in the URI path

Request: GET / GET /opengov

  • pengov/v1/

/v1/garbageschedule?location garbageschedule?location=Main%20Street HTTP/1.1 =Main%20Street HTTP/1.1 Accept: application/vnd.opengov.org.garbageschedule+json Response: HTTP/1.1 200 OK Content-Type: application/ application/vnd.opengov.org.garbageschedule+json vnd.opengov.org.garbageschedule+json {"schedule" "self": "schedule-2423", "dayOfWeek": "Monday", "oddOrEvenWeeks": "Odd"}

slide-45
SLIDE 45

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

45

Matter of taste:

  • 1. Media-­‑type ¡approach ¡most ¡

RESTful, ¡but ¡requires ¡work ¡on ¡ client ¡and ¡server ¡side. ¡ ¡

  • 2. Quali`ier, ¡second ¡best, ¡easier ¡

to ¡implement. ¡Less ¡media-­‑ types ¡to ¡keep ¡track ¡off. ¡ ¡

  • 3. URI, ¡most ¡often ¡used. ¡

Personally ¡don’t ¡like ¡it. ¡Can ¡ have ¡two ¡URIs ¡point ¡to ¡same ¡

  • resource. ¡

~ ¡personal ¡opinion ¡~ ¡

Which one is the best?

slide-46
SLIDE 46

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

46

When HTTPS isn’t enough

slide-47
SLIDE 47

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

47

General idea about authentication in REST

“REST means working with the standards of the web, and the standard for

"secure" transfer on the web is SSL. Anything else is going to be kind of funky and require extra deployment effort for clients, which will have to have encryption libraries available.”

Highest rated answer on stackoverflow regarding REST authentication schemes

slide-48
SLIDE 48

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

48

Why do we need more?

  • HTTPS doesn’t fix man-in-the-middle attack
  • It provides only transport level security
  • Has no support for message integrity or authenticity
  • REST assumes “Layered System”
  • OAuth is nice (and complex) for authentication

doesn’t handle message integrity.

  • REST doesn’t have a WS-Security standard
slide-49
SLIDE 49

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

49

~ ¡de ¡facto ¡standard ¡~ ¡

HMAC based authentication

  • Used by Google, Amazon AWS, Yahoo etc.
  • Create a signature of the complete request, using shared secret.
  • Add custom header with signature and signing user.
  • Encrypt the following with this shared secret:
  • URI, to avoid executing on different resource,
  • Verb, indicates what we want to do with a resource,
  • MD5-Header, to detect changes to the content body
  • Content-type, indicates the type of resource
  • Date header, to avoid replay
slide-50
SLIDE 50

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

50

~ ¡example ¡~ ¡

HMAC based authentication

POST /resources/rest/geo/comment HTTP/1.1[\r][\n] hmac: jos:+9tn0CLfxXFbzPmbYwq/KYuUSUI=[\r][\n] Date: Mon, 26 Mar 2012 21:34:33 CEST[\r][\n] Content-Md5: r52FDQv6V2GHN4neZBvXLQ==[\r][\n] Content-Length: 69[\r][\n] Content-Type: application/vnd.geo.comment+json; charset=UTF-8[\r][\n] Host: localhost:9000[\r][\n] Connection: Keep-Alive[\r][\n] User-Agent: Apache-HttpClient/4.1.3 (java 1.5)[\r][\n] [\r][\n] {"comment" : {"message":"blaat" , "from":"blaat" , "commentFor": 123}}

slide-51
SLIDE 51

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

51

~ ¡you ¡may ¡forget ¡everything ¡else ¡I ¡said ¡~ ¡

Parting guidelines

  • Just doing URIs and Verbs doesn’t make it RESTful
  • But that isn’t necessary a bad thing.
  • Use “Links” to describe “HOW” your service is used.
  • Describe “WHAT” is expected using media-types.
  • This isn’t a complete replacement of documentation
  • Don’t use WADL
  • Use media-types for versioning.
  • Forget what HATEOAS stands for.
slide-52
SLIDE 52

WWW.JPOINT.NL ¡ ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡JOS@JPOINT.NL ¡ ¡ ¡ ¡| ¡ ¡ ¡ ¡ ¡TWITTER: ¡@JOSDIRKSEN ¡

52

Q&A

slide-53
SLIDE 53

JPoint ¡ More ¡information; ¡look ¡at ¡http://www.jpoint.nl ¡or ¡contact ¡me. ¡

THANKS FOR COMING