1. Best Practice in Web
Service Design
Lorna Jane Mitchell
February 2010

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

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