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 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 Interface, Layered System, and (optionally) Code-on-demand. For details, see http:/ /www.ics.uci.edu/ ~ fj elding/pubs/dissertation/top.htm Thank you! Friday 20 June 14

REST Intro Friday 20 June 14

identi fj cation of resources Friday 20 June 14

identi fj cation of resources Universal identity URIs Link targets Bookmarks Entry points Friday 20 June 14

resource manipulation through representations Friday 20 June 14

resource manipulation through representations SoC data/identity/location Multiple Metadata representations Reduced dependency Processing model Friday 20 June 14

hypermedia as the engine of application state Friday 20 June 14

hypermedia as the engine of application state Connections Links Forms Flow Status Friday 20 June 14

self-descriptive messages Friday 20 June 14

self-descriptive messages Standardization Metadata Provider independence Intermediaries Caching Friday 20 June 14

What’s in the Web? Friday 20 June 14

Lots of things with URLs … Friday 20 June 14

… connected with hypermedia … Friday 20 June 14

… governed by standard formats. Friday 20 June 14

Common Misconceptions Friday 20 June 14

REST is about nice URIs T O N S ’ T I Friday 20 June 14

What makes a URI “RESTful”? 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 Friday 20 June 14

There is no such thing as a “RESTful URI” http :// example.com /customers/delete?id=13 Scheme Param Host Path Opaque ID Friday 20 June 14

Why you shouldn’t care about URIs <customer> <...> <orders href=' '> http://example.com/customers/13/orders http://xyz.org/838892AEF28CDAEFD1234/3 </customer> Hypermedia context Friday 20 June 14

REST = URI patterns + GET, PUT, POST, DELETE O N T U B , E S O L C Friday 20 June 14

Documented URIs URI Method Meaning become APIs http://ex.org/v1/customers POST create new customer http://ex.org/v1/customers/{id} GET get customer details get list of customer’s Assumptions about http://ex.org/v1/customers/{id}/orders GET details server details Versions in URIs ... ... ... become facts cause change for no good reason Friday 20 June 14

Detour: Versioning Friday 20 June 14

What are you “versioning”? ✔ Data ✔ Documentation ✔ Formats ✘ APIs Friday 20 June 14

Versioning recommendations Friday 20 June 14

Use di fg erent media types for di fg erent things Friday 20 June 14

Use version numbers in URIs to version the resource itself Friday 20 June 14

Create new resources for new aspects Friday 20 June 14

Reserve space for links Friday 20 June 14

Version your docs Friday 20 June 14

Wait, what? Friday 20 June 14

Yes, no versioning Friday 20 June 14

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.” http:/ /tools.ietf.org/html/rfc761 Friday 20 June 14

Be kind to each other Friday 20 June 14

Postel’s Law Liberal, Loose, Tolerant Liberal, Loose, Tolerant Strict, Critical, Draconian Friday 20 June 14

Client rules Server rules Don’t depend on Don’t break URI structure URI structure unnecessarily Support unknown Evolve via additional links resources Ignore unknown content Support older formats Friday 20 June 14

Friday 20 June 14

How to hypermedia-enable your service interfaces Friday 20 June 14

Step 1: Service Documents Friday 20 June 14

<?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=" http://om.archive.com/orders/ " /> <link rel="fulfilled" href="/orders/fulfilled/" /> <link rel="cancellations" href="/cancellations/" /> <link rel="reports" href="/reports/" /> </serviceDescription> { "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

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/dra fu -nottingham-json-home-03 Friday 20 June 14

Step 2: Resource Links Friday 20 June 14

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

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

Step 3: State Transition Links Friday 20 June 14

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

Hypermedia APIs = Responses with Links Y L N O T O N Friday 20 June 14

Rule #1: Don’t have clients build URIs using string concatenation Friday 20 June 14

…instead: provide recipes Friday 20 June 14

<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

<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

REST = A di fg erent approach to service interfaces E L P M I S O O T Friday 20 June 14

Point-to-point integration System B System A Friday 20 June 14

Service interfaces Client 1 Client 2 Server … Client n Friday 20 June 14

Hypermedia types Client 1 Server A Client 2 Server B Format … … Client n Server n Friday 20 June 14