Slide 1

Slide 1 text

REST API MANUAL Honza Javorek, 11/2013 Based on Steve Klabnik's great article Haters gonna HATEOAS http://timelessrepo.com/haters-gonna-hateoas

Slide 2

Slide 2 text

Honza Javorek? 1/154

Slide 3

Slide 3 text

honzajavorek.cz 2/154

Slide 4

Slide 4 text

Learn how to avoid “Bro, that's not really RESTful.” 3/154

Slide 5

Slide 5 text

REST = Representational State Transfer Fielding, Roy Thomas (2000), Architectural Styles and the Design of Network-based Software Architectures, Doctoral dissertation, University of California, Irvine no implementation details goals constraints → REST + HTTP REST × SOAP et al. 4/154

Slide 6

Slide 6 text

REST constraints ● client-server ● stateless state of the resource ● cacheable ● layered system load balancing, cache, etc. ● uniform interface guiding principles 5/154

Slide 7

Slide 7 text

uniform interface guiding principles ? 6/154

Slide 8

Slide 8 text

REST guiding principles ● identification of resources URIs ● manipulation of resources through these representations representation and it's metadata = enough information to manipulate it ● self-descriptive messages each message = enough information to process it (MIME, cache, ...) ● hypermedia as the engine of application state HATEOAS, hyperlinks, hypertext 7/154

Slide 9

Slide 9 text

Leonard Richardson's Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html 4 steps toward the glory of REST 8/154

Slide 10

Slide 10 text

4 levels of “REST support” 1. “The Swamp of POX” You’re using HTTP to make RPC calls. HTTP is only really used as a tunnel. 2.Resources Rather than making every call to a service endpoint, you have multiple endpoints that are used to represent resources, and you’re talking to them. 3.HTTP verbs You interact with resources using HTTP verbs, rather than always using POST. 4.HATEOAS Hypermedia Controls. HATEOAS. You’re 100% REST compliant. 9/154

Slide 11

Slide 11 text

HTTP REST ≠ 10/154

Slide 12

Slide 12 text

HTTP REST ≠ 10/154

Slide 13

Slide 13 text

HTTP REST ≠ čím víc bludišťáků, tím víc RESTful 10/154

Slide 14

Slide 14 text

REST can be provided over any protocol. Boring fact: Everyone implementing REST uses HTTP. HTTP REST architecture You want your API to be here 11/154

Slide 15

Slide 15 text

resources RPC ≠ 12/154

Slide 16

Slide 16 text

POST /photos.getInfo POST /photos.comments.addComment POST /photos.comments.deleteComment POST /photos.comments.editComment 13/154

Slide 17

Slide 17 text

POST /photos.getInfo POST /photos.comments.addComment POST /photos.comments.deleteComment POST /photos.comments.editComment 13/154

Slide 18

Slide 18 text

RESOURCES, MOTHERFUCKER!

Slide 19

Slide 19 text

POST /photos/add POST /comments/add POST /comments/42/delete

Slide 20

Slide 20 text

CRUD HTTP verbs →

Slide 21

Slide 21 text

POST /photos/add POST /photos/1/delete

Slide 22

Slide 22 text

VERBS, MOTHERFUCKER!

Slide 23

Slide 23 text

GET /photos/ POST /photos/ GET /photos/1 PUT /photos/1 PATCH /photos/1 DELETE /photos/1

Slide 24

Slide 24 text

Content negotiation

Slide 25

Slide 25 text

GET /photos.xml GET /photos.json GET /v1/photos.json

Slide 26

Slide 26 text

HEADERS, MOTHERFUCKER!

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

Content negotiation as we know it Accept-Language: de; q=1.0, en; q=0.5 Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1

Slide 29

Slide 29 text

Content negotiation & API formats Accept: application/json {'body': {'nipples': 2, 'legs': 2}} Accept: application/xml 2 2

Slide 30

Slide 30 text

Content negotiation & API versions Accept: application/json {'body': {'nipples': 2, 'legs': 2}} Accept: application/mattel.v1+json {'body': {'nipples': 2}} http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Slide 31

Slide 31 text

Content negotiation & language Accept-Language: en {'name': 'Barbie', 'body': ...} Accept-Language: cs {'name': 'Barbie', 'body': ...}

Slide 32

Slide 32 text

Content negotiation & language Accept-Language: en {'title': 'The Good Soldier Švejk'} Accept-Language: cs {'title': 'Osudy dobrého vojáka Švejka za světové války'}

Slide 33

Slide 33 text

HATEOAS

Slide 34

Slide 34 text

HATEOAS ● Hypertext As The Engine Of Application State ● hypertext ● engine ● application state

Slide 35

Slide 35 text

Your application is just a big state machine. se stim smiř

Slide 36

Slide 36 text

HATEOAS ● single entry endpoint to your API ● you can do whatever you need just by inspecting the API ● transitions are made by hyperlinks – URIs ● abstracting away implementation details iOS apps Sounds familiar? Yes, it's exactly how HTML and websites work.

Slide 37

Slide 37 text

GET /author/10 { 'id': 10, 'name': 'Gargamel', } GET /author/10/posts/ [ {'id': 3, 'title': 'How to cook smurfs', ...}, {'id': 2, 'title': 'How to chase smurfs', ...}, ] GET /author/10/comments/ [ {'id': 12293, 'text': 'I hate you.'}, {'id': 49939, 'text': 'Smurfs are idiots.'}, ]

Slide 38

Slide 38 text

STATE TRANSITIONS, MOTHERFUCKER!

Slide 39

Slide 39 text

GET /author/10 { 'uri': '/author/10', 'name': 'Gargamel', 'posts': '/author/10/posts/', 'comments': '/author/10/comments/', } GET /author/10/posts/ [ {'uri': '/posts/3', 'title': 'How to...', ...}, {'uri': '/posts/2', 'title': 'How to...', ...}, ] GET /author/10/comments/ [ {'uri': '/comments/12293', 'text': 'I hate you.'}, {'uri': '/comments/49939', 'text': 'Smurfs...'}, ]

Slide 40

Slide 40 text

These are nice, but... really, why should I bother?

Slide 41

Slide 41 text

RESTful API pros & cons ● Beautifully consistent and usable. API clients will love you. Look at Django REST framework's browsable APIs. ● It is the future. (Everyone says it, so it must be true.) HTTP2.0 solves the biggest flaws. HTTP2.0 async, multiplexing, compression, pipelining, etc. → ● Designed for scale. Everything is designed for massive caching and counts with presence of middleware. ● Change tolerant. Change business logic in a single place! Without the links the client must implement logic for building links. If you put this code inside your iPhone or Android clients you cannot change the URI structure on the server without breaking existing clients. If a link is present the client can follow the link. A client application does not have to repeat the business logic for deciding if a book can be purchased or downloaded. ● URIs are implementation detail. Choose a URI naming scheme that fits whatever framework or coding conventions that we find useful. 150/154

Slide 42

Slide 42 text

Conclusion ● stick to HTTP ● ensure that everything is a resource ● implement CRUD as HTTP verbs ● use content negotiation instead of crippling your URIs ● use the old mighty hypertext instead of juggling with IDs on client side 151/154

Slide 43

Slide 43 text

Other suff – best practices ● HTTP status codes ● caching ● authorization ● rate limiting ● OPTIONS ● error handling ● ... 152/154

Slide 44

Slide 44 text

whatever you use, make your API OPINIONATED & CONSISTENT 153/154

Slide 45

Slide 45 text

cast: