BIO PRESENTATION PAPER W12 6/28/2006 1:45 PM W EB S ERVICES I NTERFACE D ESIGN - P ITFALLS AND P ROVEN T ECHNIQUES Dave Mount J-Soup Softw are, Inc Better Software Conference June 26 – 29, 2006 Las Vegas, NV USA
Dave Mount Dave is the founder and president of jSoup Software, providing technology consulting services to companies that develop software. Before starting jSoup, Dave was the senior application architect for four years at BenefitPoint, an ASP for the employee benefits industry. Dave pioneered the use of Web Services at BenefitPoint and recently has been engaged in extending BenefitPoint’s client-facing API. Dave graduated from Cornell University in 1993 with a B.S. in Applied and Engineering Physics and has been working in the software industry ever since.
Web Services Interface Design Pitfalls and Proven Techniques Dave Mount President J-Soup Software, Inc. 1
Objectives ● Explain why gray matter still matters ● Show pitfalls of poor interface design ● Provide guidelines for stronger interfaces ● Discuss key elements of Web Services interface design ● Examine popular Web Services interfaces 2
A Cautionary Tale ● BenefitPoint, ASP for employee benefits industry ● Aptus Connect project, expanding services ● Problems − Inconsistent naming of operations and data − Object reuse: get vs. create and update − Security holes: inconsistent authorization checks − Failure of testing tools − Interoperability issues 3
Why Gray Matter Still Matters ● Tools make it easy ● Web Services is still emerging ● Lots of choices that will impact customers ● Interface is a contract ● Potential for serious mistakes 4
Pitfalls of Poor Design ● Exposing application ugliness − Concepts and names evolve over time − Inappropriate method granularity − Ambiguous data types, inconsistent use of types − Meaningless exceptions 5
Pitfalls of Poor Design (continued) ● Bypassing application rules − Different from browser-based perspective − Lacks context of Web-page driven process − Skipping validation − Allowing access to another user's data 6
Pitfalls of Poor Design (continued) ● Ignoring interoperability − .NET, Axis, WebLogic, etc. − WS-I basic profile ● Missing the boat − WS-Security, WS-Messaging, others − SOA 7
Proven Design Techniques ● Envision the interface from perspective of user − Use consistent names based on clear concepts − Use enumerations for static values rather than internal IDs − Structure data by concept and context − Classify exceptions and make problems explicit − Generate client stubs and test early 8
Proven Design Techniques (continued) ● Think about the future − Avoid breaking contracts − Establish a plan for versioning − Balance flexibility of operations and data types with clarity of purpose 9
Proven Design Techniques (continued) ● Take interoperability seriously − Stick to basic XML types − Avoid constructs with limited support − Follow WS-I recommendations − Accommodate .NET ● Use work-arounds for “nillable” fields 10
Proven Design Techniques (continued) ● Perform validation − Check all values and return complete list of problems − Ensure meaningful value combinations ● Let the application enforce the rules − Create tests that attempt to violate the rules − Plug holes at the application level 11
Proven Design Techniques (continued) ● Keep users straight − Require login when important − Use WS-Security or pass session ID in header ● Provide documentation − WSDL may be human-readable but... 12
Popular Public APIs ● Google, eBay, Salesforce.com ● Common features − Well documented − Good use of enumerations − Broad support for interoperability: .NET, Java, PHP, RoR, etc. 13
Wrap Up ● Use tools, especially the one in your head ● Anticipate change ● Keep an eye on standards ● Get client feedback ● Learn by example 14
Web Services Resources ● IBM's developerWorks – http://www.ibm.com/developerworks/ ● Microsoft – http://msdn.microsoft.com/webservices/ ● Web Service Interoperability Organization – http://www.ws- i.org/ ● OASIS Open – http://www.oasis-open.org/ ● Apache Web Services Project – http://ws.apache.org/ ● jSoup Software – http://www.jsoup.com/webservices/ 15
Web Services Interface Design Proven Techniques for Designing Web Services that are Consistent, Standards-Compliant and Secure Dave Mount, President J-Soup Software, Inc. April 3, 2006
Motivation Web Services interface design can seem deceptively simple. Many tools for building Web services can automatically generate a service from existing application code. While code generation accelerates development, taking design shortcuts by directly exposing application functionality or ignoring interface design altogether can lead to short- and long-term problems. The Web services perspective is different from that of a typical application. What may be intuitive and correct in object-oriented design and programming can cause problems in Web services. Also, while the users of a browser-based application interface expect quick response times, pre-populated forms, pages with clear context and navigation, the “users” of Web services very often are other applications or batch processes. To improve Web service design, it pays to step back and consider the target audience and potential use of the services. The pitfalls of exposing a poorly designed interface range from semantic inconsistencies that cause confusion and data integrity issues to serious compromises in application security. This guide offers a number of proven techniques for producing clean, stable, comprehensible Web services that are open to future enhancement. Follow these guidelines to avoid the pitfalls of poor Web services design. Background Assumptions For the purposes of this paper, a basic understanding of SOAP-based Web services is assumed. A quick Web search will uncover lots of information about Web services, and a number of websites pertaining to interface design are referenced in the endnotes of this paper. The reader with some hands-on experience developing Web services is likely to get more out of this paper than a complete newbie. Web services provide a means of integrating applications by exchanging XML-formatted messages in a defined structure. Web services consist of operations that are composed of messages, which can contain structured data. Each service has one or more modes of access, called bindings. A binding maps to a service port, which is a collection of operations. SOAP is the original and most common protocol used for packaging Web services messages and HTTP is the most commonly used transport for delivering messages. A Web service is defined by a Web services definition language file, or WSDL, which specifies the service name and location, available bindings, ports, operations, messages and custom data types. Data types are defined using XML schema directly in the WSDL or in external files that are imported into the WSDL. Web services standards are evolving rapidly, and many features, such as security, routing and transaction processing, are being added. Be sure to check the freshness date on this paper and be on the look-out for technology improvements.
Recommend
More recommend
