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