This presentation provides an introduction to RESTful service design patterns by starting at the HTTP basics, then looking at good designs and finally covering good and bad practices.

1. Understanding REST and designing for it RESTful Design

2. Robert MacLean www.sadev.co.za @rmaclean BB&D ATC Introduction HTTP Basics URI’s Methods Status Codes Content Type Authentication URI Planning Patterns Style Accidental Services Examples Actions Guidelines Anti-Patterns Security Wrap Up About me Agenda Welcome

3. REST Acronym? Representational State Transfer Source? Came about in 2000 doctoral dissertation of Roy Fielding

4. What is it? ROA – Resource Orientated Architecture WOA – Web Orientated Architecture Thanks Gartner for another TLA  It is a style NOT API Interface Official Standard A drop in replacement for SOAP

5. Benefits of REST Highly scalable Designed for HTTP Easy to consume & produce No complex request/response model. No complex XML contracts Easy to understand for you and machines URI + Method = Intent

6. HTTP Basics REST builds on HTTP so you need to know HTTP HTTP is not HTML HTTP is stateless HTTP URI Header http://www.sadev.co.za Method GET Status Code 200 Content Type text/plain Body text

7. URI Basics Hostname Scheme Query http://www.sadev.co.za/users/1/contact http://www.sadev.co.za?user=1&action=contact http://rob:pass@bbd.co.za:8044 https://bbd.co.za/index.html#about Query Hostname Scheme Userinfo Hostname Port Scheme Scheme Hostname Query Fragment

8. Method Basics Just a guide

9. Status Codes 1xx – Informational 2xx – Success 3xx – Redirection 4xx – Client Error 5xx – Server Error

10. Status Codes Examples 100 = Continue 102 = Processing 200 = OK 201 = Created 204 = No Content 206 = Partial Content 301 = Moved Permanently 302 = Found (Moved Temp) 307 = Temp Redirect 400 = Bad Request 401 = Unauthorised 402 = Payment Required 403 = Forbidden 404 = Not Found 405 = Method Not Allowed 409 = Conflict 418 = I’m a teapot 450 = Blocked by Windows Parental Controls 500 = Internal Server Error 501 = Not Implemented

11. Content Type Proper name: Internet Media Type Also known as MIME type Parts: Type, SubType, Optional Parameters x- prefix for nonstandard types or subtypes vnd. prefix for vendor specific subtypes Frowned upon by purists

12. Content Type Examples text/plain – Plain text text/xml – XML text/html – HTML image/png – PNG image audio/basic – Wave audio audio/mpeg – MPEG audio (MP3) video/quicktime – Quicktime Video application/pdf – Adobe PDF document application/javascript – JavaScript application/vnd.ms-powerpoint – PowerPoint file application/x-rar-compressed – RAR file

13. HTTP Authentication Basic Authentication Easy to do, but plain text. Easy to reverse engineer. Less of an issue when used with SSL. Digest Authentication Harder to do, still plain text. Hard (impossible?) to reverse engineer because of hashing. NTLM Authentication Hard to do, Windows specific. Hard (impossible?) to reverse engineer.

14. Header Example Request HEAD /index.html HTTP/1.1 Host: www.example.com Response HTTP/1.1 200 OK Date: Mon, 23 May 2005 22:38:34 GMT Server: Apache/1.3.3.7 (Unix) (Red-Hat/Linux) Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT Etag: "3f80f-1b6-3e1cb03b" Accept-Ranges: bytes Content-Length: 438 Connection: close Content-Type: text/html; charset=UTF-8

15. Lego Catalogue A simple system to store what LEGO’s a person owns. Want to Add bricks Set bricks status to be in use Remove bricks Get list of bricks Check if I have enough bricks Get picture of brick

16. Lego Catalogue URI HTTP Valid REST Valid Intent good

17. Lego Catalogue URI HTTP Valid REST Valid Intent good

18. Lego Catalogue URI HTTP Valid REST Valid Intent good

19. Lego Catalogue URI HTTP Valid REST Invalid Intent bad

20. Lego Catalogue URI HTTP Valid REST Invalid Intent nightmare

21. Real Life URI Example Resource: Photos Where: http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}.jpg http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}_[mstb].jpg http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{o-secret}_o.(jpg|gif|png) What: JPEG, GIF or PNG (defined in the URL) http://farm1.static.flickr.com/2/1418878_1e92283336_m.jpg

22. REST Method Style “The big four”

23. Accidental Services Accidental services do not use all methods Some URL’s offering all of them and others a limited set

24. Methods Example http://bbddb01/northwind/users[firstname=“rob%”] + POST = Error + GET = Returns everyone who begins with rob + PUT = Error + DELETE = Deletes everyone who begins with rob http://bbddb01/northwind/users + we add some input data + POST = Creates a new user + GET = Returns everyone who meets criteria + PUT = Creates/Updates a user (based on data) + DELETE = Deletes everyone who meets criteria

25. Methods Example http://bbddb01/northwind/users[firstname=“rob%”] + POST = Error + PUT = Error What would the error be? HTTP 400 would be best 405 or 500 could also be appropriate

26. What about actions? GetStoreOpenTime(Location) GET http://lc/stores/{location}/times?state=open RejectDesign(Design) POST http://lc/rejections + form data PerformBrickCount(Design) POST http://lc/design/124/brickCount GET http://lc/design/124/brickCount/2

27. Guidelines Design to be stateless Design for resources, not services Stock quote service vs. A way to work with stock resources Use cookies for self-contained state

28. Guidelines Naming: Favour nouns over verbs GET /brick/2/delete DELETE /brick/2 Shorter nice URI’s preferred, not required Do not change URI’s Use 3xx redirection if needed

29. Guidelines Give every resource an ID http://lc/brick/1 http://lc/project/planned/223 More URI’s the better

30. Guidelines Support for multiple data types or representations For data use XML and/or JSON Postfixes to define type GET /brick/2/image.jpg GET /brick/2/image.png

31. Guidelines Design with standards in mind – for example RSS & ATOM Create should return URI’s not resources Use the right HTTP methods for the right actions You are on HTTP – use the infrastructure. Proxy, Caching, Etag, Expires

32. Guidelines Hyperlinks are good <project self=“http://lc/project/753”> <bricksUsed> <brick ref=“http://lc/brick/234” /> <brick ref=“http://lc/brick/286” /> <brick ref=“http://lc/brick/12” /> </bricksUsed> <coloursUsed> <colour name=“red” code=“ff0000” ref=“http://lc/brick/red”/> </coloursUsed> </project>

33. Guidelines Offer paging <bricks self=“http://lc/bricks”> <link rel=“next” ref=“http://lc/bricks?page=20” /> … </bricks>

34. Guidelines Offer collections of information <bricks> <brick ref=“http://lc/brick/1” /> <brick ref=“http://lc/brick/2” /> <brick ref=“http://lc/brick/3” /> </brick> <bricks> <brick ref=“http://lc/brick/1”> <colour>red</colour> </brick> <brick ref=“http://lc/brick/2”> <colour>red</colour> </brick> <brick ref=“http://lc/brick/3”> <colour>red</colour> </brick> </brick>

35. Anti-Patterns Use one HTTP method – like GET for everything Often called GET or POST Tunnelling Pass everything in URI’s Assume this is a replacement for SOAP or WS*

36. Security101 Are RESTful services secure? It’s a style, not a technology so that depends on how you implement it. Are you open to SQL injection attacks? When you look at http://bbddb01/northwind/users[firstname=“rob%”], you may think so but you shouldn’t be. Because: The parameter shouldn’t be SQL If it is SQL, why are you not filtering it? Remember the old rule: Do not trust user input URI’s are user input

37. Security102 How can I do authentication? It’s built on HTTP, so everything you have for authentication in HTTP is available PLUS You could encode your authentication requirements into the input fields

38. Good Examples WCF Data Services Previously called ADO.NET Data Services & Astoria NerdDinner.com Twitter.com MediaWiki Their action’s are frowned upon by purists

39. Benefits of REST Highly scalable Designed for HTTP and stateless Easy to consume No complex request/response model. No complex XML contracts Easy to understand for you and machines URI + Method = Intent