Best Practices in Web Service Design

Best Practice in Web Service Design Lorna Jane Mitchell February 2010

A Story http://www.flickr.com/photos/james_michael_hill/254778578/

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

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 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 <

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?

Thankyou! • Lorna Mitchell • @lornajane http://joind.in/1460

http://www.lornajane.net	1170
http://lanyrd.com	84
http://www.slideshare.net	60
http://srukwebdev01.totemic.local	1
http://beta.lornajane.net	1
http://translate.googleusercontent.com	1

Best Practices in Web Service Design

by Lorna Mitchell on Feb 27, 2010

Accessibility

Categories

Upload Details

Usage Rights

6 Embeds 1,317

Statistics

Best Practices in Web Service Design Presentation Transcript