RESTful design
Download as PPTX, PDF0 likes358 views
The document provides an in-depth introduction to REST (Representational State Transfer) principles and practices, highlighting its scalability, simplicity, and HTTP-based architecture. It covers important aspects like URIs, HTTP methods, status codes, content types, authentication, and design guidelines for RESTful APIs. Additionally, it discusses common anti-patterns and emphasizes the importance of security when implementing RESTful services.
![Real Life URI ExampleResource: PhotosWhere:http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}.jpghttp://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}_[mstb].jpghttp://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](https://image.slidesharecdn.com/restfuldesign-100706075833-phpapp01/85/RESTful-design-21-320.jpg)
![Methods Examplehttp://bbddb01/northwind/users[firstname=“rob%”]+ POST = Error + GET = Returns everyone who begins with rob+ PUT = Error+ DELETE = Deletes everyone who begins with robhttp://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](https://image.slidesharecdn.com/restfuldesign-100706075833-phpapp01/85/RESTful-design-24-320.jpg)
![Methods Examplehttp://bbddb01/northwind/users[firstname=“rob%”]+ POST = Error + PUT = ErrorWhat would the error be?HTTP 400 would be best405 or 500 could also be appropriate](https://image.slidesharecdn.com/restfuldesign-100706075833-phpapp01/85/RESTful-design-25-320.jpg)
![Security101Are 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 SQLIf it is SQL, why are you not filtering it?Remember the old rule: Do not trust user inputURI’s are user input](https://image.slidesharecdn.com/restfuldesign-100706075833-phpapp01/85/RESTful-design-36-320.jpg)
RESTful design
- 1. Understanding REST and designing for itRESTful Design
- 2. Robert MacLeanwww.sadev.co.za@rmacleanBB&D ATCIntroductionHTTP BasicsURI’sMethodsStatus CodesContent TypeAuthenticationURI PlanningPatternsStyleAccidental ServicesExamplesActionsGuidelinesAnti-PatternsSecurityWrap UpAbout meAgendaWelcome
- 3. RESTAcronym? Representational State Transfer Source?Came about in 2000 doctoral dissertation of Roy Fielding
- 4. What is it?ROA – Resource Orientated ArchitectureWOA – Web Orientated ArchitectureThanks Gartner for another TLA It is a styleNOT APIInterfaceOfficial StandardA drop in replacement for SOAP
- 5. Benefits of RESTHighly scalableDesigned for HTTPEasy to consume & produceNo complex request/response model.No complex XML contractsEasy to understand for you and machinesURI + Method = Intent
- 6. HTTP BasicsREST builds on HTTP so you need to know HTTPHTTP is not HTMLHTTP is statelessHTTPURIHeaderhttp://www.sadev.co.zaMethodGETStatus Code200Content Typetext/plainBodytext
- 8. Method BasicsJust a guide
- 9. Status Codes1xx – Informational 2xx – Success3xx – Redirection4xx – Client Error5xx – Server Error
- 10. Status Codes Examples100 = Continue102 = Processing200 = OK201 = Created204 = No Content206 = Partial Content301 = Moved Permanently 302 = Found (Moved Temp)307 = Temp Redirect400 = Bad Request401 = Unauthorised402 = Payment Required403 = Forbidden404 = Not Found405 = Method Not Allowed409 = Conflict418 = I’m a teapot450 = Blocked by Windows Parental Controls500 = Internal Server Error501 = Not Implemented
- 11. Content TypeProper name: Internet Media TypeAlso known as MIME typeParts: Type, SubType, Optional Parametersx- prefix for nonstandard types or subtypesvnd. prefix for vendor specific subtypesFrowned upon by purists
- 12. Content Type Examplestext/plain – Plain texttext/xml – XML text/html – HTML image/png – PNG imageaudio/basic – Wave audioaudio/mpeg – MPEG audio (MP3)video/quicktime – Quicktime Videoapplication/pdf – Adobe PDF documentapplication/javascript – JavaScriptapplication/vnd.ms-powerpoint – PowerPoint fileapplication/x-rar-compressed – RAR file
- 13. HTTP AuthenticationBasic AuthenticationEasy to do, but plain text. Easy to reverse engineer. Less of an issue when used with SSL.Digest AuthenticationHarder to do, still plain text. Hard (impossible?) to reverse engineer because of hashing. NTLM AuthenticationHard to do, Windows specific. Hard (impossible?) to reverse engineer.
- 14. Header ExampleRequestHEAD /index.htmlHTTP/1.1 Host: www.example.com ResponseHTTP/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 CatalogueA simple system to store what LEGO’s a person owns. Want toAdd bricksSet bricks status to be in useRemove bricksGet list of bricksCheck if I have enough bricksGet picture of brick
- 16. Lego Catalogue URIHTTP ValidREST ValidIntent good
- 17. Lego Catalogue URIHTTP ValidREST ValidIntent good
- 18. Lego Catalogue URIHTTP ValidREST ValidIntent good
- 19. Lego Catalogue URIHTTP ValidREST InvalidIntent bad
- 20. Lego Catalogue URIHTTP ValidREST InvalidIntent nightmare
- 21. Real Life URI ExampleResource: PhotosWhere:http://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}.jpghttp://farm{farm-id}.static.flickr.com/{server-id}/{id}_{secret}_[mstb].jpghttp://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 ServicesAccidental services do not use all methodsSome URL’s offering all of them and others a limited set
- 24. Methods Examplehttp://bbddb01/northwind/users[firstname=“rob%”]+ POST = Error + GET = Returns everyone who begins with rob+ PUT = Error+ DELETE = Deletes everyone who begins with robhttp://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 Examplehttp://bbddb01/northwind/users[firstname=“rob%”]+ POST = Error + PUT = ErrorWhat would the error be?HTTP 400 would be best405 or 500 could also be appropriate
- 26. What about actions?GetStoreOpenTime(Location)GET http://lc/stores/{location}/times?state=openRejectDesign(Design)POST http://lc/rejections + form dataPerformBrickCount(Design)POST http://lc/design/124/brickCountGET http://lc/design/124/brickCount/2
- 27. GuidelinesDesign to be statelessDesign for resources, not servicesStock quote service vs. A way to work with stock resourcesUse cookies for self-contained state
- 28. GuidelinesNaming: Favour nouns over verbsGET /brick/2/deleteDELETE /brick/2Shorter nice URI’s preferred, not requiredDo not change URI’sUse 3xx redirection if needed
- 29. GuidelinesGive every resource an IDhttp://lc/brick/1http://lc/project/planned/223More URI’s the better
- 30. GuidelinesSupport for multiple data types or representationsFor data use XML and/or JSONPostfixes to define typeGET /brick/2/image.jpgGET /brick/2/image.png
- 31. GuidelinesDesign with standards in mind – for example RSS & ATOMCreate should return URI’s not resourcesUse the right HTTP methods for the right actionsYou are on HTTP – use the infrastructure.Proxy, Caching, Etag, Expires
- 32. GuidelinesHyperlinks 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. GuidelinesOffer paging<bricks self=“http://lc/bricks”> <link rel=“next” ref=“http://lc/bricks?page=20” /> …</bricks>
- 34. GuidelinesOffer 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-PatternsUse one HTTP method – like GET for everythingOften called GET or POST TunnellingPass everything in URI’sAssume this is a replacement for SOAP or WS*
- 36. Security101Are 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 SQLIf it is SQL, why are you not filtering it?Remember the old rule: Do not trust user inputURI’s are user input
- 37. Security102How can I do authentication?It’s built on HTTP, so everything you have for authentication in HTTP is availablePLUSYou could encode your authentication requirements into the input fields
- 38. Good ExamplesWCF Data ServicesPreviously called ADO.NET Data Services & AstoriaNerdDinner.comTwitter.comMediaWikiTheir action’s are frowned upon by purists
- 39. Benefits of RESTHighly scalableDesigned for HTTP and statelessEasy to consumeNo complex request/response model.No complex XML contractsEasy to understand for you and machinesURI + Method = Intent