Best Practices in Web Service Design
Upcoming SlideShare
Loading in...5
×
 

Best Practices in Web Service Design

on

  • 45,078 views

 

Statistics

Views

Total Views
45,078
Views on SlideShare
43,732
Embed Views
1,346

Actions

Likes
20
Downloads
629
Comments
1

8 Embeds 1,346

http://www.lornajane.net 1170
http://lanyrd.com 111
http://www.slideshare.net 60
http://srukwebdev01.totemic.local 1
http://beta.lornajane.net 1
http://translate.googleusercontent.com 1
http://www.linkedin.com 1
https://twitter.com 1
More...

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
  • 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
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Best Practices in Web Service Design Best Practices in Web Service Design Presentation Transcript

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