Best Practices in Web Service Design

53,025 views
52,395 views

Published on

Published in: Technology
1 Comment
28 Likes
Statistics
Notes
  • 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
No Downloads
Views
Total views
53,025
On SlideShare
0
From Embeds
0
Number of Embeds
1,361
Actions
Shares
0
Downloads
830
Comments
1
Likes
28
Embeds 0
No embeds

No notes for slide

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

×