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?

Thankyou!

• Lorna Mitchell• @lornajane

http://joind.in/1460