Post on 19-May-2015
transcript
Lorna Jane MitchellFebruary 2010
Best Practice in Web Service Design
http://www.flickr.com/photos/james_michael_hill/254778578/
A Story
Aims of a Web Service
• Expose system functionality• Assist modular application
architecture• Enable scalability
Empower Users!
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
Web
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
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 <
HTTP Status Codes
Code Meaning
200 OK
302 Found
301 Moved
401 Not Authorised
403 Forbidden
404 Not Found
500 Internal Server Error
Headers
• Authorization• Cookie and Set-Cookie• Cache-Control• User-Agent• Accept• Content-Type
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
HTTP Verbs
• GET• POST• PUT• DELETE
Service
Service Types
• SOAP• *-RPC
– XML-RPC– JSON-RPC
• REST
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
RPC Services
• Remote Procedure Call• Similar to library• Call function with arguments• Body format can change
– XML makes XML-RPC– JSON makes JSON-RPC
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
Design
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
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
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
Small APIs
• Beware adding functionality• Small, flexible APIs• Few methods as possible• Easy to use
Consistency
• Important to retain– naming conventions– parameter validation rules– parameter order
• Just as you would in library code
Statelessness
• Request alone contains all information needed
• No session data• Resource does not need to be in
known state• Same operation performs same
outcome
Versions and Formats
• Always include a version parameter• Handle multiple formats
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!
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
Error Feedback
• Help users help themselves• Descriptive feedback• Stack errors• Use existing/similar format
Authentication Mechanisms
• Depends completely on the environment
• Web services are like web applications• Application interfaces have the same
considerations whether internal or external
Authentication Options
• Require authentication on every request
• Authenticate once and use a token• Restrict token validity• Application or web server
authentication• Just like sessions
Heartbeat Method
• A method which does nothing• No authentication• Requires correct request format• Gives basic feedback• Shows that service is alive
Build It And They Will Come
• ... Or not!• Users need a service to be
– accessible– documented– robust– reliable– simple– predictable
Delivering A Web Service
• Like packaging software• Give users tools to help themselves• Avoid support calls
Documentation
• WSDL• PHPDoc can help• Simple examples/tutorials• API spec
– formats– variable names– data types– error information
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
In Summary
• Web Services != Rocket Science• HTTP theory• Service types• Design considerations• Effective Delivery
Resources
• http://php.net• RESTful Web Services by Leonard
Richardson, Sam Ruby• http://curl.haxx.se/• http://benramsey.com• http://lornajane.net
Questions?