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