REST: I don't Think it Means What You Think it Does Stefan Tilkov | - - PowerPoint PPT Presentation

▶
rest i don t think it means what you think it does
SMART_READER_LITE
LIVE PREVIEW

REST: I don't Think it Means What You Think it Does Stefan Tilkov | - - PowerPoint PPT Presentation

Jul 16, 2023 98 likes •833 views

REST: I don't Think it Means What You Think it Does Stefan Tilkov | @stilkov GOTO Amsterdam, 20 June 2014 Friday 20 June 14 REST: An architectural style de fj ned by the constraints Client-Server, Stateless Communication, Caching, Uniform

slide-1
SLIDE 1

REST: I don't Think it Means What You Think it Does

Stefan Tilkov | @stilkov GOTO Amsterdam, 20 June 2014

Friday 20 June 14

slide-2
SLIDE 2

REST: An architectural style defjned by the constraints Client-Server, Stateless Communication, Caching, Uniform Interface, Layered System, and (optionally) Code-on-demand.

For details, see http:/ /www.ics.uci.edu/ ~fjelding/pubs/dissertation/top.htm Thank you!

Friday 20 June 14

slide-3
SLIDE 3

REST Intro

Friday 20 June 14

slide-4
SLIDE 4

identifjcation

  • f resources

Friday 20 June 14

slide-5
SLIDE 5

identifjcation

  • f resources

URIs Universal identity Link targets Bookmarks Entry points

Friday 20 June 14

slide-6
SLIDE 6

resource manipulation through representations

Friday 20 June 14

slide-7
SLIDE 7

resource manipulation through representations

Metadata SoC data/identity/location Multiple representations Reduced dependency Processing model

Friday 20 June 14

slide-8
SLIDE 8

hypermedia as the engine

  • f application state

Friday 20 June 14

slide-9
SLIDE 9

hypermedia as the engine

  • f application state

Connections Links Forms Flow Status

Friday 20 June 14

slide-10
SLIDE 10

self-descriptive messages

Friday 20 June 14

slide-11
SLIDE 11

self-descriptive messages

Metadata Standardization Provider independence Intermediaries Caching

Friday 20 June 14

slide-12
SLIDE 12

What’s in the Web?

Friday 20 June 14

slide-13
SLIDE 13

Lots of things with URLs …

Friday 20 June 14

slide-14
SLIDE 14

… connected with hypermedia …

Friday 20 June 14

slide-15
SLIDE 15

… governed by standard formats.

Friday 20 June 14

slide-16
SLIDE 16

Common Misconceptions

Friday 20 June 14

slide-17
SLIDE 17

REST is about nice URIs

I T ’ S N O T

Friday 20 June 14

slide-18
SLIDE 18
  • 1. http://example.com/customers/format?drive=c
  • 2. http://example.com/customers/getDetails?id=13
  • 3. http://example.com/customers/delete?id=13
  • 4. http://example.com/customers/13
  • 5. http://example.com/customers/13/edit

What makes a URI “RESTful”?

Friday 20 June 14

slide-19
SLIDE 19

There is no such thing as a “RESTful URI”

example.com /customers/delete?id=13

Scheme Path Host Param

:// http

Opaque ID

Friday 20 June 14

slide-20
SLIDE 20

Why you shouldn’t care about URIs

<customer> <...> <orders href=' '> </customer> http://example.com/customers/13/orders http://xyz.org/838892AEF28CDAEFD1234/3

Hypermedia context

Friday 20 June 14

slide-21
SLIDE 21

REST = URI patterns + GET, PUT, POST, DELETE

C L O S E , B U T N O

Friday 20 June 14

slide-22
SLIDE 22

URI Method Meaning http://ex.org/v1/customers POST create new customer http://ex.org/v1/customers/{id} GET get customer details http://ex.org/v1/customers/{id}/orders GET get list of customer’s details ... ... ...

Versions in URIs cause change for no good reason Documented URIs become APIs Assumptions about server details become facts

Friday 20 June 14

slide-23
SLIDE 23

Detour: Versioning

Friday 20 June 14

slide-24
SLIDE 24

What are you “versioning”? Data Documentation Formats APIs

✔ ✔ ✔ ✘

Friday 20 June 14

slide-25
SLIDE 25

Versioning recommendations

Friday 20 June 14

slide-26
SLIDE 26

Use difgerent media types for difgerent things

Friday 20 June 14

slide-27
SLIDE 27

Use version numbers in URIs to version the resource itself

Friday 20 June 14

slide-28
SLIDE 28

Create new resources for new aspects

Friday 20 June 14

slide-29
SLIDE 29

Reserve space for links

Friday 20 June 14

slide-30
SLIDE 30

Version your docs

Friday 20 June 14

slide-31
SLIDE 31

Wait, what?

Friday 20 June 14

slide-32
SLIDE 32

Yes, no versioning

Friday 20 June 14

slide-33
SLIDE 33

Postel’s law

http:/ /tools.ietf.org/html/rfc761

“TCP implementations should follow a general principle of robustness: Be conservative in what you do, be liberal in what you accept from others.”

Friday 20 June 14

slide-34
SLIDE 34

Be kind to each other

Friday 20 June 14

slide-35
SLIDE 35

Postel’s Law

Liberal, Loose, Tolerant Strict, Critical, Draconian Liberal, Loose, Tolerant

Friday 20 June 14

slide-36
SLIDE 36

Don’t break URI structure unnecessarily Evolve via additional resources Support older formats

Server rules

Don’t depend on URI structure Support unknown links Ignore unknown content

Client rules

Friday 20 June 14

slide-37
SLIDE 37

Friday 20 June 14

slide-38
SLIDE 38

How to hypermedia-enable your service interfaces

Friday 20 June 14

slide-39
SLIDE 39

Step 1: Service Documents

Friday 20 June 14

slide-40
SLIDE 40

<?xml version="1.0" encoding="UTF-8"?> <serviceDescription xml:base="http://om.example.com"> <link rel="all" href="/orders/" /> <link rel="received" href="/orders/received/" /> <link rel="accepted" href="/orders/accepted/" /> <link rel="rejected" href="/orders/rejected/" /> <link rel="cancelled" href="/orders/cancelled/" /> <link rel="fulfilled" href="/orders/fulfilled/" /> <link rel="cancellations" href="/cancellations/" /> <link rel="reports" href="/reports/" /> </serviceDescription> <link rel="fulfilled" href="http://om.archive.com/orders/" /> { "serviceDescription" : { "base": "http://om.example.com", "links": [ { "rel": "all", "href": "/orders/" }, { "rel": "all", "href": "/orders/" }, { "rel": "received", "href": "/orders/received/" }, { "rel": "accepted", "href": "/orders/accepted/" }, { "rel": "rejected", "href": "/orders/rejected/" }, { "rel": "cancelled", "href": "/orders/cancelled/" }, { "rel": "fulfilled", "href": "/orders/fulfilled/" }, { "rel": "cancellations", "href": "/cancellations/" }, { "rel": "reports", "href": "/reports/" } ] } }

Friday 20 June 14

slide-41
SLIDE 41

JSON Home

{ "resources": { "http://example.org/rel/widgets": { "href": "/widgets/" }, "http://example.org/rel/widget": { "href-template": "/widgets/{widget_id}", "href-vars": { "widget_id": "http://example.org/param/widget" }, "hints": { "allow": ["GET", "PUT", "DELETE", "PATCH"], "representations": ["application/json"], "accept-patch": ["application/json-patch"], "accept-post": ["application/xml"], "accept-ranges": ["bytes"] } } } }

http:/ /tools.ietf.org/html/drafu-nottingham-json-home-03

Friday 20 June 14

slide-42
SLIDE 42

Step 2: Resource Links

Friday 20 June 14

slide-43
SLIDE 43

GET /order/123

{ "order": { "date": "2013-07-02", "total": 1240.02, "..." : "...", "links" : [ {"rel" : "self", "href" : "http://example.com/orders/123"}, {"rel" : "contacts", "href" : "http://example.org/A3BEF1"}, ... ] } }

Friday 20 June 14

slide-44
SLIDE 44

GET /order/123

{ "order": { "date": "2013-07-02", "total": 1240.02, "..." : "...", "links" : { "self": "http://example.com/orders/123", "contacts": "http://example.org/A3BEF1", ... } } }

Your future extensions

Friday 20 June 14

slide-45
SLIDE 45

Step 3: State Transition Links

Friday 20 June 14

slide-46
SLIDE 46

{ "order": { "state" : "received", "..." : "...", "links" : [ {"rel" : "cancel", "href" : "http://..."}, {"rel" : "accept", "href" : "http://..."}, {"rel" : "reject", "href" : "http://..."}, ... ] } }

Friday 20 June 14

slide-47
SLIDE 47

Hypermedia APIs = Responses with Links

N O T O N L Y

Friday 20 June 14

slide-48
SLIDE 48

Rule #1: Don’t have clients build URIs using string concatenation

Friday 20 June 14

slide-49
SLIDE 49

…instead: provide recipes

Friday 20 June 14

slide-50
SLIDE 50

<form action='http://example.com/search' method='GET'> Search for: <input type='text' name='query'> <input type='submit'> </form> { "rel": "search", "template": "http://example.com/search?q={query}" }

Friday 20 June 14

slide-51
SLIDE 51

<form action='http://example.com/add' method='POST'> First: <input type='text' name='first'> Last: <input type='text' name='last'> Birthday: <input type='date' name='bdate'> <input type='submit'> </form> {"target": "http://example.com/add", "rel": "add", "template": { "first": "...", "last": "...", "bdate": "..." } }

Friday 20 June 14

slide-52
SLIDE 52

REST = A difgerent approach to service interfaces

T O O S I M P L E

Friday 20 June 14

slide-53
SLIDE 53

System B

Point-to-point integration

System A

Friday 20 June 14

slide-54
SLIDE 54

Client 1

Service interfaces

Server Client 2 Client n

…

Friday 20 June 14

slide-55
SLIDE 55

Client 1

Hypermedia types

Client 2 Client n

…

Server A Server B Server n

…

Format

Friday 20 June 14

slide-56
SLIDE 56

application/atom+xml

Friday 20 June 14

slide-57
SLIDE 57

application/opensearchdescription+xml

Friday 20 June 14

slide-58
SLIDE 58

application/vnd.collection+json

Friday 20 June 14

slide-59
SLIDE 59

application/hal+json

Friday 20 June 14

slide-60
SLIDE 60

application/vnd.siren+json

Friday 20 June 14

slide-61
SLIDE 61

text/html

Friday 20 June 14

slide-62
SLIDE 62

Detour: HTML

Friday 20 June 14

slide-63
SLIDE 63

<order> <shippingAddress>Paris, France</shippingAddress> <items> <item> <productDescription>iPad</productDescription> <quantity>1</quantity> <price>699</price> </item> </items> <link href="http://om.example.com/cancellations" rel="cancel" /> <link href="https://om.example.com/orders/123/payment" rel="payment" /> </order>

Friday 20 June 14

slide-64
SLIDE 64

<html xmlns="http://www.w3.org/1999/xhtml"> <body> <div class="order"> <p class="shippingAddress">Paris, France</p> <ul class="items"> <li class="item"> <p class="productDescription">iPad</p> <p class="quantity">1</p> <p class="price">699</p> </li> </ul> <a href="http://om.example.com/cancellations" rel="cancel">cancel</a> <a href="https://om.example.com/orders/123/payment" rel="payment">payment</a> </div> </body> </html>

Friday 20 June 14

slide-65
SLIDE 65

Benefjts of Using HTML as Your Hypermedia Format

Ubiquity Well-known, well supported HM controls A pretty good standard client Lots of programming tools UIs as a side-efgect

Friday 20 June 14

slide-66
SLIDE 66

Friday 20 June 14

slide-67
SLIDE 67

Summary

Friday 20 June 14

slide-68
SLIDE 68

Link context over pretty URIs

Friday 20 June 14

slide-69
SLIDE 69

Hypermedia over URI APIs

Friday 20 June 14

slide-70
SLIDE 70

Hypermedia flows over static links

Friday 20 June 14

slide-71
SLIDE 71

Generalized formats over services

Friday 20 June 14

slide-72
SLIDE 72

Q&A

Stefan Tilkov, @stilkov stefan.tilkov@innoq.com Phone: +49 170 471 2625

innoQ Deutschland GmbH

  • Krischerstr. 100

40789 Monheim am Rhein Germany Phone: +49 2173 3366-0

innoQ Schweiz GmbH info@innoq.com

  • Gewerbestr. 11

CH-6330 Cham Switzerland Phone: +41 41 743 0116

www.innoq.com

Ohlauer Straße 43 10999 Berlin Germany Phone: +49 2173 3366-0 Robert-Bosch-Straße 7 64293 Darmstadt Germany Phone: +49 2173 3366-0 Radlkoferstraße 2 D-81373 München Telefon +49 (0) 89 741185-270

Friday 20 June 14