Best Practices in Web Service Design
- 1. Best Practice in Web Service Design Lorna Jane Mitchell February 2010
- 3. Aims of a Web Service • Expose system functionality • Assist modular application architecture • Enable scalability Empower Users!
- 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. Web
- 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. 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. HTTP Status Codes Code Meaning 200 OK 302 Found 301 Moved 401 Not Authorised 403 Forbidden 404 Not Found 500 Internal Server Error
- 9. Headers • Authorization • Cookie and Set-Cookie • Cache-Control • User-Agent • Accept • Content-Type
- 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. HTTP Verbs • GET • POST • PUT • DELETE
- 12. Service
- 13. Service Types • SOAP • *-RPC – XML-RPC – JSON-RPC • REST
- 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. 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. 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. Design
- 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. 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. 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. Small APIs • Beware adding functionality • Small, flexible APIs • Few methods as possible • Easy to use
- 22. Consistency • Important to retain – naming conventions – parameter validation rules – parameter order • Just as you would in library code
- 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. Versions and Formats • Always include a version parameter • Handle multiple formats
- 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. 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. Error Feedback • Help users help themselves • Descriptive feedback • Stack errors • Use existing/similar format
- 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. 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. Heartbeat Method • A method which does nothing • No authentication • Requires correct request format • Gives basic feedback • Shows that service is alive
- 31. Build It And They Will Come • ... Or not! • Users need a service to be – accessible – documented – robust – reliable – simple – predictable
- 32. Delivering A Web Service • Like packaging software • Give users tools to help themselves • Avoid support calls
- 33. Documentation • WSDL • PHPDoc can help • Simple examples/tutorials • API spec – formats – variable names – data types – error information
- 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. In Summary • Web Services != Rocket Science • HTTP theory • Service types • Design considerations • Effective Delivery
- 36. Resources • http://php.net • RESTful Web Services by Leonard Richardson, Sam Ruby • http://curl.haxx.se/ • http://benramsey.com • http://lornajane.net
- 37. Questions?
- 38. Thankyou! • Lorna Mitchell • @lornajane http://joind.in/1460