Best Practices in Web Service Design
-
Upload
lorna-mitchell -
Category
Technology
-
view
44.420 -
download
1
Transcript of Best Practices in Web Service Design
![Page 1: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/1.jpg)
Lorna Jane MitchellFebruary 2010
Best Practice in Web Service Design
![Page 2: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/2.jpg)
http://www.flickr.com/photos/james_michael_hill/254778578/
A Story
![Page 3: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/3.jpg)
Aims of a Web Service
• Expose system functionality• Assist modular application
architecture• Enable scalability
Empower Users!
![Page 4: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/4.jpg)
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
![Page 5: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/5.jpg)
Web
![Page 6: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/6.jpg)
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
![Page 7: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/7.jpg)
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 libidn/1.15 > 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_W4IpJdCIG7; expires=Thu, 29-Dec-2011 11:53:32 GMT; path=/; domain=.google.co.uk < Set-Cookie: NID=30=xm_tayHyAuPiERmCeIv3kiHczSQgm-Nt6DWlGVKKqTrAhT2BhqDiqswwr4VRdMdKX7T-A46lBcfV-mS0WZGQqfq-Px5097pdZ3x4R2jRboXU5i8lU2GqM5ql7Zs7zmv3; expires=Wed, 30-Jun-2010 11:53:32 GMT; path=/; domain=.google.co.uk; HttpOnly < Server: gws < X-XSS-Protection: 0 < Transfer-Encoding: chunked <
![Page 8: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/8.jpg)
HTTP Status Codes
Code Meaning
200 OK
302 Found
301 Moved
401 Not Authorised
403 Forbidden
404 Not Found
500 Internal Server Error
![Page 9: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/9.jpg)
Headers
• Authorization• Cookie and Set-Cookie• Cache-Control• User-Agent• Accept• Content-Type
![Page 10: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/10.jpg)
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
![Page 11: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/11.jpg)
HTTP Verbs
• GET• POST• PUT• DELETE
![Page 12: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/12.jpg)
Service
![Page 13: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/13.jpg)
Service Types
• SOAP• *-RPC
– XML-RPC– JSON-RPC
• REST
![Page 14: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/14.jpg)
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
![Page 15: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/15.jpg)
RPC Services
• Remote Procedure Call• Similar to library• Call function with arguments• Body format can change
– XML makes XML-RPC– JSON makes JSON-RPC
![Page 16: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/16.jpg)
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
![Page 17: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/17.jpg)
Design
![Page 18: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/18.jpg)
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
![Page 19: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/19.jpg)
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
![Page 20: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/20.jpg)
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
![Page 21: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/21.jpg)
Small APIs
• Beware adding functionality• Small, flexible APIs• Few methods as possible• Easy to use
![Page 22: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/22.jpg)
Consistency
• Important to retain– naming conventions– parameter validation rules– parameter order
• Just as you would in library code
![Page 23: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/23.jpg)
Statelessness
• Request alone contains all information needed
• No session data• Resource does not need to be in
known state• Same operation performs same
outcome
![Page 24: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/24.jpg)
Versions and Formats
• Always include a version parameter• Handle multiple formats
![Page 25: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/25.jpg)
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!
![Page 26: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/26.jpg)
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
![Page 27: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/27.jpg)
Error Feedback
• Help users help themselves• Descriptive feedback• Stack errors• Use existing/similar format
![Page 28: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/28.jpg)
Authentication Mechanisms
• Depends completely on the environment
• Web services are like web applications• Application interfaces have the same
considerations whether internal or external
![Page 29: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/29.jpg)
Authentication Options
• Require authentication on every request
• Authenticate once and use a token• Restrict token validity• Application or web server
authentication• Just like sessions
![Page 30: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/30.jpg)
Heartbeat Method
• A method which does nothing• No authentication• Requires correct request format• Gives basic feedback• Shows that service is alive
![Page 31: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/31.jpg)
Build It And They Will Come
• ... Or not!• Users need a service to be
– accessible– documented– robust– reliable– simple– predictable
![Page 32: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/32.jpg)
Delivering A Web Service
• Like packaging software• Give users tools to help themselves• Avoid support calls
![Page 33: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/33.jpg)
Documentation
• WSDL• PHPDoc can help• Simple examples/tutorials• API spec
– formats– variable names– data types– error information
![Page 34: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/34.jpg)
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
![Page 35: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/35.jpg)
In Summary
• Web Services != Rocket Science• HTTP theory• Service types• Design considerations• Effective Delivery
![Page 36: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/36.jpg)
Resources
• http://php.net• RESTful Web Services by Leonard
Richardson, Sam Ruby• http://curl.haxx.se/• http://benramsey.com• http://lornajane.net
![Page 37: Best Practices in Web Service Design](https://reader034.fdocuments.net/reader034/viewer/2022052619/555a2808d8b42a900d8b49c0/html5/thumbnails/37.jpg)
Questions?