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




...
Web. Service. Design

• WEB - we'll talk about HTTP itself and
  how the web makes an ideal vehicle
  for conveying inform...
Web
The Web: HTTP

• HyperText Transport Protocol: the
  "wires" that the web uses to
  communicate.
• HTTP includes meta 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....
HTTP Status Codes

     Code      Meaning
     200       OK
     302       Found
     301       Moved
     401       Not A...
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...
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...
RPC Services

•   Remote Procedure Call
•   Similar to library
•   Call function with arguments
•   Body format can change...
REST

• REpresentational State Transfer
• A series of concepts
• Generally uses HTTP (HyperText
  Transfer Protocol)
• URL...
Design
Tools to Make a Web Service

• Lots of options
• By hand
  – Using PHP language features
• With helper components
  – e.g....
Designing a Web Service

• Who/what will consume this?
• What service/format is appropriate?
  – multiple formats where po...
Services and Unit Testing

• Easiest application of unit testing
• With API tests
  – be confident of spotting changes
  –...
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...
Statelessness

• Request alone contains all information
  needed
• No session data
• Resource does not need to be in
  kno...
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...
Error Handling

• Success is not the only outcome
• Users will encounter failure
  – it might be their fault
  – how you h...
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
• Applicatio...
Authentication Options

• Require authentication on every
  request
• Authenticate once and use a token
• Restrict token v...
Heartbeat Method

•   A method which does nothing
•   No authentication
•   Requires correct request format
•   Gives basi...
Build It And They Will Come

• ... Or not!
• Users need a service to be
  – accessible
  – documented
  – robust
  – relia...
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
...
Examples

• Tutorials with examples
• Include full request and response
  information in examples
• Troubleshooting tips a...
In Summary

•   Web Services != Rocket Science
•   HTTP theory
•   Service types
•   Design considerations
•   Effective D...
Resources

• http://php.net
• RESTful Web Services by Leonard
  Richardson, Sam Ruby
• http://curl.haxx.se/
• http://benra...
Questions?
Thankyou!

• Lorna Mitchell
• @lornajane




 http://joind.in/1460
Upcoming SlideShare
Loading in...5
×

Best Practices in Web Service Design

46,269

Published on

Published in: Technology
1 Comment
24 Likes
Statistics
Notes
  • who can write a PHP function, know what jQuery is, can handle their CSS well, but would like some insider info on how a web service is built from scratch. How should I organize my files, where should I keep my functions, how should I start planning the thing, how should I connect to the database, how should I handle AJAX calls and how should I manage my 404 pages are just some of the questions I try to shed some light on here.

    Link: http://biitbook.com/books/detail/how-to-create-a-web-service-start-to-finish
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total Views
46,269
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
746
Comments
1
Likes
24
Embeds 0
No embeds

No notes for slide

Best Practices in Web Service Design

  1. 1. Best Practice in Web Service Design Lorna Jane Mitchell February 2010
  2. 2. A Story http://www.flickr.com/photos/james_michael_hill/254778578/
  3. 3. Aims of a Web Service • Expose system functionality • Assist modular application architecture • Enable scalability Empower Users!
  4. 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. 5. Web
  6. 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. 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. 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. 9. Headers • Authorization • Cookie and Set-Cookie • Cache-Control • User-Agent • Accept • Content-Type
  10. 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. 11. HTTP Verbs • GET • POST • PUT • DELETE
  12. 12. Service
  13. 13. Service Types • SOAP • *-RPC – XML-RPC – JSON-RPC • REST
  14. 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. 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. 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. 17. Design
  18. 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. 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. 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. 21. Small APIs • Beware adding functionality • Small, flexible APIs • Few methods as possible • Easy to use
  22. 22. Consistency • Important to retain – naming conventions – parameter validation rules – parameter order • Just as you would in library code
  23. 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. 24. Versions and Formats • Always include a version parameter • Handle multiple formats
  25. 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. 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. 27. Error Feedback • Help users help themselves • Descriptive feedback • Stack errors • Use existing/similar format
  28. 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. 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. 30. Heartbeat Method • A method which does nothing • No authentication • Requires correct request format • Gives basic feedback • Shows that service is alive
  31. 31. Build It And They Will Come • ... Or not! • Users need a service to be – accessible – documented – robust – reliable – simple – predictable
  32. 32. Delivering A Web Service • Like packaging software • Give users tools to help themselves • Avoid support calls
  33. 33. Documentation • WSDL • PHPDoc can help • Simple examples/tutorials • API spec – formats – variable names – data types – error information
  34. 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. 35. In Summary • Web Services != Rocket Science • HTTP theory • Service types • Design considerations • Effective Delivery
  36. 36. Resources • http://php.net • RESTful Web Services by Leonard Richardson, Sam Ruby • http://curl.haxx.se/ • http://benramsey.com • http://lornajane.net
  37. 37. Questions?
  38. 38. Thankyou! • Lorna Mitchell • @lornajane http://joind.in/1460
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×