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

Transcription

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

2 REST: An architectural style defined by the constraints Client-Server, Stateless Communication, Caching, Uniform Interface, Layered System, and (optionally) Code-on-demand. For details, see ~fielding/pubs/dissertation/top.htm Thank you!

3 REST Intro

4 identification of resources

5 identification of resources Universal identity URIs Link targets Bookmarks Entry points

6 resource manipulation through representations

7 resource manipulation through representations SoC data/identity/location Multiple representations Processing model Reduced dependency

8 hypermedia as the engine of application state

9 hypermedia as the engine of application state Links Connections Forms Flow Status

10 self-descriptive messages

11 self-descriptive messages Standardization Provider independence Metadata Caching Intermediaries

12 What s in the Web?

13 Lots of things with URLs

14 connected with hypermedia

15 governed by standard formats.

16 Common Misconceptions

17 REST is about nice URIs IT S NOT

18 What makes a URI RESTful?

19 There is no such thing as a RESTful URI http :// example.com /customers/delete?id=13 Scheme Host Path Param Opaque ID

20 Why you shouldn t care about URIs <customer> <...> <orders href=' </customer> Hypermedia context

21 REST = URI patterns + GET, PUT, POST, DELETE CLOSE, BUT NO

22 Documented URIs URI Method Meaning become APIs POST create new customer GET get customer details GET Versions in URIs cause change for no good reason get list of customer s Assumptions about details server details become facts

23 Detour: Versioning

24 What are you versioning? Data Documentation Formats APIs

25 Versioning recommendations

26 Use different media types for different things

27 Use version numbers in URIs to version the resource itself

28 Create new resources for new aspects

29 Reserve space for links

30 Version your docs

31 Wait, what?

32 Yes, no versioning

33 Yes, no explicit versioning

34 Postel s law TCP implementations should follow a general principle of robustness: Be conservative in what you do, be liberal in what you accept from others.

35 Be kind to each other

36 Postel s Law Liberal, Loose, Tolerant Liberal, Loose, Tolerant Strict, Critical, Draconian

37 Client rules Don t depend on URI structure Support unknown links Ignore unknown content Server rules Don t break URI structure unnecessarily Evolve via additional resources Support older formats

38

39 How to hypermedia-enable your service interfaces

40 Step 1: Service Documents

41 <?xml version="1.0" encoding="utf-8"?> <servicedescription xml:base=" <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/" /> <link rel="fulfilled" href=" /> </servicedescription> { "servicedescription" : { "base": " "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/" } ] } }

42 { } JSON Home "resources": { " { "href": "/widgets/" }, " { "href-template": "/widgets/{widget_id}", "href-vars": { "widget_id": " }, "hints": { "allow": ["GET", "PUT", "DELETE", "PATCH"], "representations": ["application/json"], "accept-patch": ["application/json-patch"], "accept-post": ["application/xml"], "accept-ranges": ["bytes"] } } }

43 Step 2: Resource Links

44 GET /order/123 { "order": { "date": " ", "total": , "..." : "...", "links" : [ {"rel" : "self", "href" : " {"rel" : "contacts", "href" : " ] } }

45 GET /order/123 { "order": { "date": " ", "total": , "..." : "...", "links" : { "self": " "contacts": " } } } Your future extensions

46 Step 3: State Transition Links

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

48 Hypermedia APIs = Responses with Links NOT ONLY

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

50 instead: provide recipes

51 <form action=' method='get'> Search for: <input type='text' name='query'> <input type='submit'> </form> { "rel": "search", "template": " }

52 <form action=' 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": " "rel": "add", "template": { "first": "...", "last": "...", "bdate": "..." } }

53 REST = A different approach to service interfaces TOO SIMPLE

54 Point-to-point integration System B System A

55 Service interfaces Client 1 Client 2 Server Client n

56 Hypermedia types Client 1 Server A Client 2 Format Server B Client n Server n

57 application/atom+xml

58 application/opensearchdescription+xml

59 application/vnd.collection+json

60 application/hal+json

61 application/vnd.siren+json

62 text/html

63 Detour: HTML

64 <order> <shippingaddress>paris, France</shippingAddress> <items> <item> <productdescription>ipad</productdescription> <quantity>1</quantity> <price>699</price> </item> </items> <link href=" rel="cancel" /> <link href=" payment" rel="payment" /> </order>

65 <html xmlns=" <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=" rel="cancel">cancel</a> <a href=" rel="payment">payment</a> </div> </body> </html>

66 Benefits 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-effect

67

68 Summary

69 Link context over pretty URIs

70 Hypermedia over URI APIs

71 Hypermedia flows over static links

72 Generalized formats over services

73 Q&A Stefan Phone: innoq Deutschland GmbH Krischerstr Monheim am Rhein Germany Phone: Ohlauer Straße Berlin Germany Phone: Robert-Bosch-Straße Darmstadt Germany Phone: Radlkoferstraße 2 D München Telefon +49 (0) innoq Schweiz GmbH Gewerbestr. 11 CH-6330 Cham Switzerland Phone: info@innoq.com

74 Bonus misconception: REST is for services only WRONG

75 REST as the Web s Architectural Style 1991 HTTP HTTP 1.0 Browsers Command line clients 1997 HTTP 1.1 (RFC 2068) 1999 HTTP 1.1 (RFC 2616) 2000 REST 2000 SOAP/1.1 Proxies Crawlers Servers

76 (Resource-oriented Client Architecture)

77 Web-centric web UIs

78 Server-side components ROCA Avoid HTML, JS, CSS Trade Familiarity for Complexity Session-centric Server-side POSH Client-side components Web-centric Single Page Apps Advanced Client Frameworks Server-side REST APIs

79 Make your HTML semantic

80 Use Javascript unobtrusively

81 Use URIs to identify a single meaningful concept

82 Don t disable Browser Features use them

83 ROCA