Tweet
Tweet

Slide 1

Slide 1 text

REST: Not an Intro Stefan Tilkov | @stilkov SoundCloud, 2 July 2013

Slide 2

Slide 2 text

REST Intro

Slide 3

Slide 3 text

(not really)

Slide 4

Slide 4 text

identi cation of resources

Slide 5

Slide 5 text

resource manipulation through representations

Slide 6

Slide 6 text

hypermedia as the engine of application state

Slide 7

Slide 7 text

self-descriptive messages

Slide 8

Slide 8 text

What’s in the Web?

Slide 9

Slide 9 text

Lots of things with URLs …

Slide 10

Slide 10 text

… connected with hypermedia …

Slide 11

Slide 11 text

… governed by standard formats.

Slide 12

Slide 12 text

REpresentational State Transfer

Slide 13

Slide 13 text

Common Misconceptions

Slide 14

Slide 14 text

REST is about nice URIs IT’S NOT

Slide 15

Slide 15 text

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”?

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

Why you shouldn’t care about URIs <...> http://example.com/customers/13/orders http://xyz.org/838892AEF28CDAEFD1234/3 Hypermedia context

Slide 18

Slide 18 text

REST = CRUD NOT AT ALL

Slide 19

Slide 19 text

Minor di erences

Slide 20

Slide 20 text

POST GET PUT DELETE Create Read Update Delete ‣ When used for creation, server decides about URI ‣ Can also invoke arbitrary processing ‣ Can also be used for creation with known URI ‣ Not to be used for partial updates, idempotent

Slide 21

Slide 21 text

Major di erence

Slide 22

Slide 22 text

‣ Operations on data ‣ Business logic in caller Create Read Update Delete

Slide 23

Slide 23 text

GET PUT POST DELETE (+ Representations + URIs + Hypermedia) ‣Di erent interface style ‣No change in logic responsibilities

Slide 24

Slide 24 text

Data Data Access Business Rules Service Logic Service Interface WSDL SOAP WS-* XML Operations Parameters Messages HTTP JSON XML Resources Hypermedia Representations

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

Detour: Versioning

Slide 28

Slide 28 text

What are you “versioning”? Data Documentation Formats APIs ✔ ✔ ✔ ✘

Slide 29

Slide 29 text

Versioning recommendations

Slide 30

Slide 30 text

Use di erent media types for di erent things

Slide 31

Slide 31 text

Use version numbers in URIs to version the resource itself

Slide 32

Slide 32 text

Create new resources for new aspects

Slide 33

Slide 33 text

Reserve space for links

Slide 34

Slide 34 text

Version your docs

Slide 35

Slide 35 text

Wait, what?

Slide 36

Slide 36 text

Yes, no versioning

Slide 37

Slide 37 text

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.”

Slide 38

Slide 38 text

Be kind to each other

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

How to hypermedia-enable your service interfaces

Slide 43

Slide 43 text

Step 1: Service Documents

Slide 44

Slide 44 text

{ "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/" } ] } }

Slide 45

Slide 45 text

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 -nottingham-json-home-03

Slide 46

Slide 46 text

Step 2: Resource Links

Slide 47

Slide 47 text

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"}, ... ] } }

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

Step 3: State Transition Links

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

Detour: Link Relations

Slide 52

Slide 52 text

Client Server

Slide 53

Slide 53 text

Web Linking (RFC 5988) HTTP/1.1 200 OK Link: ;rel="prev" Link: ;rel="next" HTTP/1.1 200 OK Link: ;rel="http://example.com/rels/own" Link: ;rel="prev" Link: ; rel="http://www.iana.org/assignments/relation/prev"

Slide 54

Slide 54 text

No content

Slide 55

Slide 55 text

Hypermedia APIs = Responses with Links NOT ONLY

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

…instead: provide recipes

Slide 58

Slide 58 text

Search for: { "rel": "search", "template": "http://example.com/search?q={query}" }

Slide 59

Slide 59 text

First: Last: Birthday: {"target": "http://example.com/add", "rel": "add", "template": { "first": "...", "last": "...", "bdate": "..." } }

Slide 60

Slide 60 text

REST = A di erent approach to service interfaces TOO SIMPLE

Slide 61

Slide 61 text

System B Point-to-point integration System A

Slide 62

Slide 62 text

Client 1 Service interfaces Server Client 2 Client n …

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

application/atom+xml

Slide 65

Slide 65 text

application/opensearchdescription+xml

Slide 66

Slide 66 text

application/vnd.collection+json

Slide 67

Slide 67 text

application/hal+json

Slide 68

Slide 68 text

text/html

Slide 69

Slide 69 text

Detour: HTML

Slide 70

Slide 70 text

Paris, France iPad 1 699

Slide 71

Slide 71 text

Paris, France

  • iPad

    1

    699

cancel payment

Slide 72

Slide 72 text

http://schema.org

Slide 73

Slide 73 text

Avatar

Director: James Cameron (born August 16, 1954) Science fiction

Slide 74

Slide 74 text

Avatar

Director: James Cameron (born August 16, 1954) Science fiction

Slide 75

Slide 75 text

Avatar

Director: James Cameron (born August 16, 1954) Science fiction Trailer

Slide 76

Slide 76 text

No content

Slide 77

Slide 77 text

Summary

Slide 78

Slide 78 text

Link context over pretty URIs

Slide 79

Slide 79 text

Process logic over CRUD

Slide 80

Slide 80 text

Hypermedia over URI APIs

Slide 81

Slide 81 text

Hypermedia flows over static links

Slide 82

Slide 82 text

Generalized formats over services

Slide 83

Slide 83 text

Q&A Stefan Tilkov, @stilkov [email protected] Phone: +49 170 471 2625 innoQ Deutschland GmbH Krischerstr. 100 40789 Monheim am Rhein Germany Phone: +49 2173 3366-0 innoQ Schweiz GmbH [email protected] 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 Germany Phone: +49 2173 3366-0 Radlkoferstraße 2 D-81373 München Telefon +49 (0) 89 741185-270