Successfully reported this slideshow.

Best Practices in Web Service Design

60,046 views

Published on

Published in: Technology
  • who can write a PHP function, know what jQuery is, can handle their CSS well, but would like some insider info on how a web service is built from scratch. How should I organize my files, where should I keep my functions, how should I start planning the thing, how should I connect to the database, how should I handle AJAX calls and how should I manage my 404 pages are just some of the questions I try to shed some light on here.

    Link: http://biitbook.com/books/detail/how-to-create-a-web-service-start-to-finish
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Best Practices in Web Service Design

  1. 1. Best Practice in Web Service Design Lorna Jane Mitchell February 2010
  2. 2. A Story http://www.flickr.com/photos/james_michael_hill/254778578/
  3. 3. Aims of a Web Service • Expose system functionality • Assist modular application architecture • Enable scalability Empower Users!
  4. 4. Web. Service. Design • WEB - we'll talk about HTTP itself and how the web makes an ideal vehicle for conveying information • SERVICE - understanding the service types and how to choose • DESIGN - designing a robust and useful API, techniques for anyone specifying/implementing, either at high level or in code
  5. 5. Web
  6. 6. The Web: HTTP • HyperText Transport Protocol: the "wires" that the web uses to communicate. • HTTP includes meta information as part of the request headers • We can use this rather than reinventing formats for the info
  7. 7. Web Request Anatomy > GET / HTTP/1.1 > User-Agent: curl/7.19.5 (i486-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libid > Host: www.google.co.uk > Accept: */* > < HTTP/1.1 200 OK < Date: Tue, 29 Dec 2009 11:53:32 GMT < Expires: -1 < Cache-Control: private, max-age=0 < Content-Type: text/html; charset=ISO-8859-1 < Set-Cookie: PREF=ID=938ea5e5be0edfd5:TM=1262087612:LM=1262087612:S=i4OvD_W expires=Thu, 29-Dec-2011 11:53:32 GMT; path=/; domain=.google.co.uk < Set-Cookie: NID=30=xm_tayHyAuPiERmCeIv3kiHczSQgm-Nt6DWlGVKKqTrAhT2BhqDiqsw A46lBcfV-mS0WZGQqfq-Px5097pdZ3x4R2jRboXU5i8lU2GqM5ql7Zs7zmv3; expires=Wed, 30 GMT; path=/; domain=.google.co.uk; HttpOnly < Server: gws < X-XSS-Protection: 0 < Transfer-Encoding: chunked <
  8. 8. HTTP Status Codes Code Meaning 200 OK 302 Found 301 Moved 401 Not Authorised 403 Forbidden 404 Not Found 500 Internal Server Error
  9. 9. Headers • Authorization • Cookie and Set-Cookie • Cache-Control • User-Agent • Accept • Content-Type
  10. 10. Content-Type and Accept • Usually a common mime type, e.g: – text/html – text/xml – application/json • We can parse accordingly • Be consistent in return formats
  11. 11. HTTP Verbs • GET • POST • PUT • DELETE
  12. 12. Service
  13. 13. Service Types • SOAP • *-RPC – XML-RPC – JSON-RPC • REST
  14. 14. SOAP • Just "soap" • Defined XML format • Also includes definition for error format • Wrappers available for most languages • Optionally uses a WSDL to describe the service – Web Service Description Language
  15. 15. RPC Services • Remote Procedure Call • Similar to library • Call function with arguments • Body format can change – XML makes XML-RPC – JSON makes JSON-RPC
  16. 16. REST • REpresentational State Transfer • A series of concepts • Generally uses HTTP (HyperText Transfer Protocol) • URLs are resource locations • Verbs tell the service what to do • Status codes indicate what the outcome was
  17. 17. Design
  18. 18. Tools to Make a Web Service • Lots of options • By hand – Using PHP language features • With helper components – e.g. PEAR modules • Within a framework custom module • From an MVC system
  19. 19. Designing a Web Service • Who/what will consume this? • What service/format is appropriate? – multiple formats where possible • What functionality is needed? • Up-front design is recommended
  20. 20. Services and Unit Testing • Easiest application of unit testing • With API tests – be confident of spotting changes – update tests when making changes • Test request/response for known datasets • Could use sample database
  21. 21. Small APIs • Beware adding functionality • Small, flexible APIs • Few methods as possible • Easy to use
  22. 22. Consistency • Important to retain – naming conventions – parameter validation rules – parameter order • Just as you would in library code
  23. 23. Statelessness • Request alone contains all information needed • No session data • Resource does not need to be in known state • Same operation performs same outcome
  24. 24. Versions and Formats • Always include a version parameter • Handle multiple formats
  25. 25. Status Codes • Typically associated with REST – HTTP response codes • Useful in other APIs too • Headline news: success or type of failure • MVC tools may not use these by default • Highly recommended!
  26. 26. Error Handling • Success is not the only outcome • Users will encounter failure – it might be their fault – how you handle it is the measure of your service • Failure handling = robustness
  27. 27. Error Feedback • Help users help themselves • Descriptive feedback • Stack errors • Use existing/similar format
  28. 28. Authentication Mechanisms • Depends completely on the environment • Web services are like web applications • Application interfaces have the same considerations whether internal or external
  29. 29. Authentication Options • Require authentication on every request • Authenticate once and use a token • Restrict token validity • Application or web server authentication • Just like sessions
  30. 30. Heartbeat Method • A method which does nothing • No authentication • Requires correct request format • Gives basic feedback • Shows that service is alive
  31. 31. Build It And They Will Come • ... Or not! • Users need a service to be – accessible – documented – robust – reliable – simple – predictable
  32. 32. Delivering A Web Service • Like packaging software • Give users tools to help themselves • Avoid support calls
  33. 33. Documentation • WSDL • PHPDoc can help • Simple examples/tutorials • API spec – formats – variable names – data types – error information
  34. 34. Examples • Tutorials with examples • Include full request and response information in examples • Troubleshooting tips and known issues • Full API Documentation – simpler to generate from PHPDoc
  35. 35. In Summary • Web Services != Rocket Science • HTTP theory • Service types • Design considerations • Effective Delivery
  36. 36. Resources • http://php.net • RESTful Web Services by Leonard Richardson, Sam Ruby • http://curl.haxx.se/ • http://benramsey.com • http://lornajane.net
  37. 37. Questions?
  38. 38. Thankyou! • Lorna Mitchell • @lornajane http://joind.in/1460

×