08_0132344823_06.qxd 6/13/07 4:46 PM Page 125 Chapter 6 W I L S O N , J A M I E Service Contracts (Standardization and Design) 5 0 Profiling this Principle 5 1 Types of Service Contract Standardization Contracts and Service DesignB U Risks Associated with Service Contract Design 6.1 Contracts Explained 6.2 6.3 6.4 6.5 6.6 More About Service Contracts 6.7 Case Study Example SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 126 S ervice contracts are a focal point of service design because they are central to just about everything services do. Although at a fundamental level this principle simply requires the use of formal or standardized contracts (Figure 6.1), it actually implies much W more. Each individual part of the contract needs to be carefully measured and refined I components of service-oriented soluand because contracts are also core architectural tions, several of the other principles directly L influence how they are positioned, designed, and ultimately utilized. S Figure 6.1 The fundamental role of this principle is to ensure the consistent expression of service capabilities and the overall purpose of the service as defined by the parent service context. O N , J A 6.1 Contracts Explained M Before we explore the meaning, dynamics, and application of this principle, let’s first I as to how contracts have been used in establish some general background information E products. different types of computing platforms and vendor 5 As with many terms in the IT industry, “contract” 0 is one that can have different meanings when associated with automation solutions. 5 For example, it is relatively common to view a contract as the equivalent of a technical interface. When it comes to services 1 within SOA, we have a slightly broader definition. A contract for a service (or a service B providing technical constraints and contract) establishes the terms of engagement, requirements as well as any semantic information the service owner wishes to make U Technical Contracts in Abstract public. A service contract can consist of a group of service description documents, each of which describes a part of the service. A Web service contract, for example, can be comprised of the following service description documents: SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 127 127 6.1 Contracts Explained • WSDL definition • XML schema definition • WS-Policy description A service contract is always comprised of one or more technical service descriptions designed for runtime consumption, but there are also cases when non-technical documents are required to supplement the technical details. Both are considered valid parts W of the overall contract (Figure 6.2). Figure 6.2 Possible service description documents that can comprise a contract for a service implemented as a Web service. The subset of these documents that establishes the technical interface for the service can be considered the technical service contract. I L S O N , J A NOTE M This chapter is primarily concerned with technical service description I documents. Therefore, when we refer to the service contract, a technical E service contract is implied unless otherwise indicated. Having stated that, it should be further noted that service level agreements and other human consumable service description documents can contain highly technical content. The term “technical service5contract” is used simply to refer to service description documents that 0 are programmatically consumed at runtime. 5 1 Origins of Service Contracts B Contracts have been used by different types of automation systems almost for as long as U information technology has existed. Interactions between two standalone software programs are based on a fundamental design where the data required to invoke and exchange information between the programs is pre-defined and based on a formal, technical specification. This is what is expressed in a technical contract. Figures 6.3 and 6.4 show examples of traditional forms of technical contracts. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM 128 Page 128 Chapter 6: Service Contracts (Standardization and Design) Figure 6.3 In a classic client-server model, the client program connects to a server-side program, such as a database. In this case, a technical contract may be comprised of the database protocol and a predefined query syntax or language. Figure 6.4 In a traditional distributed model, a component existing as a standalone program interacts with other components. Each provides a technical interface that can be accessed by any compatible program. W I L S O N , J A M I E 5 0 5 In the past, technical contracts have commonly 1 been represented by a form of technical interface known as the application programming interface (API). An API library can be B accessed by a client program installed locally on the same computer as the API, or U remotely. The latter variation is most common in distributed architectures, where components require local representations of the contracts (called proxies) to interact with components located on different servers. The Interface Definition Language (IDL) and the Abstract Syntax Notation 1 (ASN.1) were frequently used to express technical contracts for remote invocation frameworks, such as those based on remote procedure calls (RPCs). A sample fragment of IDL syntax is provided in Example 6.1. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 129 129 6.1 Contracts Explained long Multiply([in] long number1, [in] long number2); Example 6.1 A Multiply capability expressed in traditional IDL. It receives two input values and returns the result of the multiplication. Web services established a non-proprietary distributed communications framework that introduced the Web Services Description Language (WSDL) as the core part of a technical service contract (Example 6.2). W Closely associated with WSDL is the XML Schema language used to define the data model for messages exchanged via Web servI ices and the WS-Policy language through which policy assertions can be defined and attached to various parts of the WSDL. L S O N , Example 6.2 A Multiply capability partially expressed as part of a WSDL definition. Input values are received via a message that is separately defined from the message that returns the results of the multiplication. (Not shown are the corresponding message and data type constructs.) J A M Historically, technical contracts created as part of custom designed automation soluI programs for one or more specific and tions have been tailored to represent software E packaged software systems that supply pre-identified clients. Exceptions to this include a generic API (or API set) based on a specific development platform. The API would provide common functions, openly accessible to any compatible client programs (for exam5 ple class libraries or GUI frameworks). 0 A common principle associated with object-oriented design encouraged the creation of 5 reusable components. This often implied that the resulting component interface would 1 advent of service-oriented computing has be sufficiently generic to facilitate reuse. The placed an unprecedented emphasis on reuse B and the design of agnostic solution logic, elevating the importance of this style of U contract design. The more a service can be reused, the more entrenched its contract will become and, as a result, the more pressure there is to deliver service contracts capable of standing the test of time. As we will discover in this and subsequent chapters, much of service-orientation is dedicated to ensuring that service contracts establish a balanced expression of a service’s purpose and capabilities in support of reuse and other key strategic goals of serviceoriented computing. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 130 4:46 PM Page 130 Chapter 6: Service Contracts (Standardization and Design) SUMMARY OF KEY POINTS • Technical contracts are an established part of IT. Whenever two programs or two units of programming logic need to connect, some form of technical contract is required. • A service contract can consist of technical and non-technical service description documents. W I 6.2 Profiling this Principle L with a focus on its definition and the Table 6.1 provides a concise profile of the principle primary design characteristics it is expected to Sfoster. O Principle Profile N , Short Definition “Services share standardized contracts.” Long Definition “Services within the same service inventory are in compliance J design standards.” with the same contract Goals • To enable services M with a meaningful level of natural interoperability within the boundary of a service inventory. ThisI reduces the need for data transformation because consistent data models are used for inforE mation exchange. A • To allow the purpose and capabilities of services to be 5 intuitively understood. The consismore easily and tency with which 0 service functionality is expressed through service contracts increases interpretability and 5 the overall predictability of service endpoints throughout a service inventory. 1 Note that these goals B are further supported by other service-orientation principles as well. U Design Characteristics • A service contract (comprised of a technical interface or one or more service description documents) is provided with the service. • The service contract is standardized through the application of design standards. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 131 131 6.2 Profiling this Principle Implementation Requirements The fact that contracts need to be standardized can introduce significant implementation requirements to organizations that do not have a history of using standards. For example: • Design standards and conventions need to ideally be in place prior to the delivery of any service in order to ensure adequately W scoped standardization. (For those organizations that have already produced ad-hoc Web I services, retro-fitting strategies may need to be employed.) L • Formal processes S need to be introduced to ensure that services are modeled and designed consistently, incorO design principles, conventions, and porating accepted standards. N • Because achieving standardized Web service contracts , generally requires a “contract first” approach to service-oriented design, the full application of this princiJ demand the use of development tools ple will often capable of importing a customized service contract A without imposing changes. M • Appropriate skill-sets are required to carry out the I design processes with the chosen tools. modeling and When working E with Web services, the need for a high level of proficiency with XML schema and WSDL languages is practically unavoidable. WS-Policy expertise may also be5required. These and other 0 requirements can add up to a noticeable transition effort that goes well beyond technology 5 adoption. 1 Web Service Region of Influence Because this principle is focused solely on the content of B the service contract, its influence is limited to the contract and related processing U logic within a typical Web service. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 132 6/14/07 8:07 AM Page 132 Chapter 6: Service Contracts (Standardization and Design) W I L S Figure 6.5 O Figure 6.6 in the upcoming Types of Service Contract N shows specifically which parts Standardization section of a typical Web,service contract can be affected. Table 6.1 A profile for the Standardized Service Contract principle. J A NOTE M Design standards and standardization in general are first explained in the Design Fundamentals section of ChapterI 3. Furthermore, this principle is also commonly defined as “Services share E a formal contract.” The term “standardized” is used here to more clearly communicate the relationship of this design principle with the use of design standards. • • 5 SUMMARY OF KEY 0 POINTS This principle advocates the use of formal, 5standardized service contracts. The standardization of service contracts can 1 be challenging, especially within larger service inventories. B U 6.3 Types of Service Contract Standardization As part of a transition toward a service-oriented architecture, we need to assemble an inventory of services, many of which will have been deliberately designed as reusable resources. Ultimately, our goal is to reach a state where we can fulfill new business automation requirements by minimizing the amount of custom development effort and instead reuse more and more of the available services. This sounds like a logical plan in SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 133 6.3 Types of Service Contract Standardization 133 theory, but to carry this out in real life requires some serious attention to the design of each service contract, as standardization is applied on several primary levels. Standardization of Functional Service Expression When services become commonplace within an enterprise, there is significant benefit to having each service express the details of its respective functional domains using the same conventions. Specifically, the application of functional expression conventions to W services increases the ease with which they are eventually interpreted by humans (and tools) at design-time and ultimately resultsI in a service-oriented enterprise that is intuitive and easily navigated. L S the meaning of each service, reuse opporBecause effort is made to consistently clarify tunities for those with an agnostic contextO are more easily identified. Also because the chances of misinterpretation are reduced, the risk of project teams inadvertently creatN ing new services with conflicting or redundant logic is mitigated. , As illustrated in Figure 6.6, the application of design standards that affect functional service expression can shape many parts of a typical Web service contract. Example 6.3 J expression standard. demonstrates the application of a functional A M Listing #1 I E 0 5 Listing #2 1 B U Example 6.3 The message definitions in Listing #1 are awkward and reference XML schema element names that seem very specific to this operation. Listing #2 represents a version of the same message definitions to which functional expression standards were applied, resulting in the use of more generic naming conventions and generic data type references. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 134 6/13/07 4:46 PM Page 134 Chapter 6: Service Contracts (Standardization and Design) W I L S O N , J A Figure 6.6 M Specific constructs within common Web service description documents that are affected by functional expression I design standards. E Standardization of Service Data Representation The technical interface description that forms the base of any service contract will almost 5 always include a formal definition of the input and/or output data required by each 0 generally includes a data type. When service capability. The detail of this definition 5 schemas, data models are typically comworking with Web services and associated XML prised of complex data types that organize related pieces of information into a formal 1 structure. This form of standardization advocates keeping schemas and associated data B types for specific sets of data in alignment across services to whatever extent feasible. U For example, when building services as Web services in larger enterprise environments, the context established by each service boundary will usually not be exclusive to one body of data. An Invoice Web service will represent a collection of invoice-related functions and will therefore be primarily responsible for processing invoice data. However, even though it will be positioned as a primary endpoint for that body of functionality, it SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 135 6.3 Types of Service Contract Standardization 135 will likely not be the only service to work with invoice data. There could easily be several services that represent functionality requiring access to invoice-related information. It is easy to create schemas for specific services that are tailored to how these services need to represent data (Figure 6.7). It can lead to very efficient schema designs that are streamlined to only represent data that is relevant to the functionality encapsulated by the service. However, this approach can cause many problems. W I L S O N , J A M I One of the key goals of service-oriented computing is to allow for the agile and even adhoc assembly of service compositions. It is E through service compositions that we will be Figure 6.7 A set of WSDL definitions for which a corresponding set of XML schemas has been custom tailored. This has the appearance of a very clean contract architecture, but it can seriously undermine the interoperability potential of an SOA. exercising most of the reuse opportunities that come our way. If two service capabilities within a composition represent the same 5 type of data using different representations (data models, schemas), then their relationship is based on non-standardized data rep0 resentation. This scenario usually leads to the need for data transformation. 5 Even though adequate transformation technology is available to overcome data model 1 disparity, it is undesirable to use it. In fact, much of the standardization effort around B service contract design is focused on “transformation avoidance,” as explained in the Contracts and Service Design section of this U chapter. In the Web services world, schemas can be designed and implemented separately from the service capabilities (operations) that utilize them to represent the structure and typing of message content. As a result, a data representation architecture can be established and standardized somewhat independently from the parent service layer. This allows for the application of a design pattern known as Schema Centralization, which SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 136 6/13/07 4:46 PM Page 136 Chapter 6: Service Contracts (Standardization and Design) advocates the definition of one “official” schema for each information set. Web service contracts can then share these centralized schemas. For example, if one schema representing invoice data is defined, any Web service with an operation that needs to access or process invoice data would use the same invoice schema. The result is standardized service data representation. The application of this pattern also encourages the creation of entity schemas—schemas that represent data associated with a particular business entity, as illustrated by the use of the ClaimHeader and W ClaimsDetail schemas in Figure 6.8. I L S O N , J A Figure 6.8 M end up sharing the same data WSDL definitions that share common XML schemas models for messages. Should the Web services I represented by these WSDL definitions ever need to interact as part of a composition, they will already have established a meaningful extent of intrinsic interoperability. E It is worth noting that in the real Web services world, this level of data representation 5 many of which revolve around the govstandardization can pose daunting challenges, 0 ernance of the standards and the schemas themselves. As we established in Chapter 4, SOA does not require global data model standardization. An established design pattern 5 called the Domain Inventory pattern supports the partitioning of an enterprise into sep1 arate domains that can be independently standardized and governed. B Achieving a meaningful level of standardization can prove to be highly beneficial in that U it supports the creation of effective service compositions and improves both the efficiency with which these services can be delivered and the efficiency with which they carry out their functions at runtime. Note also that when applying the Schema Centralization pattern, service contracts are not limited to the use of centralized schemas (such as entity schemas). Additional SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 137 6.3 Types of Service Contract Standardization 137 schemas providing service-specific types are frequently also required. However, the notable benefit to incorporating a centralized set of schemas is that this one set of schemas can be maintained in support of multiple services (as opposed to multiple sets of disparate schemas requiring separate, on-going maintenance). FOR EXAMPLE An international financial services company divided its enterprise up into business W domains, each representing a boundary in which XML schemas were standardized (an I patterns). This established an autonomous implementation of the aforementioned design data representation architecture in each domain. L Services are currently being designed for two of these domains with the goal of establishing separately governed service S inventories. O Within each inventory, services are expected to repeatedly share centralized XML N schemas representing common business documents (also referred to as “entity-centric schemas”). A primary objective of this effort, is a dramatic reduction in data transformation requirements. J Standardization of Service Policies A WS-Policy definitions add a separate layerM of potential abstraction to service contracts, allowing for policy logic to be expressed through individual policy assertions that can I be contained within physically separate policy definition documents. Standardization E comes into play on a number of levels, depending on the nature of the policies and the extent to which polices are used in general. 5 0 When standardizing services with separate 5 policy definitions, the focal point is generally on the syntax used to express policy assertions. Whereas some policy assertions are 1 predefined via existing specifications (such as WS-SecurityPolicy and WS-ReliableMesB saging), others can be customized using proprietary vocabularies that express business rules or internal corporate business policies. U Proprietary Assertion Vocabularies Much in the same way XML schema supports the creation of an abstract data representation layer (by allowing for the expression of data models that are not bound to any one proprietary database platform), policy definitions introduce an opportunity to establish abstract vocabularies used specifically to extend the Web service contract with policyrelated validation logic. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM 138 Page 138 Chapter 6: Service Contracts (Standardization and Design) This, however, can only be achieved when such vocabularies are standardized across a service inventory. Otherwise, service consumers are in constant danger of forming unhealthy dependencies on a service’s underlying implementation (as explained in the Contract-to-Implementation Coupling section of Chapter 7). Parameters and Nested Polices Policy assertions can be nested or expressed through the use of parameters. Nested polW by the system policy processor. Assericy assertions are always checked and validated tions expressed with parameters are ignoredIby most processors and therefore need to be checked by the underlying service logic. An L exception to this is when the service is hosted by a proprietary vendor runtime environment that provides a policy processor S capable of validating parameters expressing assertions that were pre-defined and proO vided by the vendor platform itself. N It is generally considered a best practice to always use nested policy assertions. How, ever, it may sometimes be suitable to use parameters when having to absolutely express proprietary assertions or when requiring the flexibility to express assertions that only apply to a subset of consumers. In this case, J the consumer program requires a foreknowledge of how the service will process the assertions within its underlying logic. A This, of course, ties back to the need for standardized assertion vocabularies, as explained in the previous section. However, M it also raises the need for a related design convention associated with the use of parameters and nested policies. How and when I these parts of the WS-Policy language should E be applied needs to be explicitly stated within design standards to avoid the creation of inconsistent policy definitions. 5 0 definitions to be created for individual While it is relatively common for custom policy Web services, because policy assertions can be 5separated into separate policy definition documents, policies can be modularized allowing 1 some to even be centralized. Applying the concept of centralization to polices B essentially allows for the creation of a base policy definition containing broad, generalized assertions. More specialized asserU Modularizing and Centralizing Policies tions can be placed into separate policy definitions that can then be attached to the same WSDL definition when the Web service is invoked during a specific runtime scenario or if variations of the service contract need to be created for different types of consumers (Figure 6.9). SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 139 6.3 Types of Service Contract Standardization 139 W I L Figure 6.9 S A security policy is defined containing assertions that apply to all WSDL definitions. However, only one of these Web service contracts O needs to be further extended with a specialized assertion associated with claims processing. N Structural Standards , Policies can impact service contract structure in a variety of ways. Individual policy assertions can apply to different parts of a WSDL definition and can be attached to those J parts in different ways. Furthermore, the manner in which some assertions are strucA turally expressed can also vary. For example, optional assertions can be defined using a M wsp:optional attribute, or a normalized compact form that relies upon the use of the form that explicitly defines each option. I E need to be taken into account when stanThese types of structural design considerations dardizing service contracts. Structural disparity, especially within highly reused and centralized policy definitions, can lead to eventual governance challenges. • • 5 0 SUMMARY OF KEY POINTS 5 The main areas in which standardization is applied to services are functional 1 expression, data representation, and policies. B Naming conventions play a large role in ensuring that the functionality of servU ices is consistently expressed. • Data representation standardization comes down to how the underlying data model of a service is defined. By increasing the consistency between service data models, interoperability is improved. • Policy standardization primarily revolves around the creation of standardized assertion vocabularies and the consistent use of WS-Policy language features. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 140 6/13/07 4:46 PM Page 140 Chapter 6: Service Contracts (Standardization and Design) 6.4 Contracts and Service Design Contracts form the foundation for communication between services and therefore represent the most fundamental architectural element of an SOA. Service-oriented design is a process dedicated to ensuring that necessary factors and issues are taken into account when shaping a service contract through service-orientation. Up next is a collection of design considerations specific to the application of this principle. W I A key to understanding what it takes to make the standardization of data models hapL pen within an organization is knowing more about why it has historically been such a S challenging goal to accomplish. O With a focus on Web services, here are some common reasons contracts are not N standardized: , • they were auto-generated by development tools Data Representation Standardization and Transformation Avoidance • they were part of purchased service adapters J A • design standards were ignored M Once implemented and part of the production I environment, non-standardized Web service contracts result in the creation and implementation of different data models repE • no design standards were in place when they were created resenting the same bodies of data. To overcome these differences requires the use of a data transformation technology and the definition of mapping logic between one 5 into an actual software component, such schema and another. This map is implemented as an XSLT style sheet, which subsequently 0executes transformation logic at runtime every time the services need to exchange information. 5 Data transformation technologies provide important features essential to enabling con1 nectivity within integrated enterprise architectures. However, when standardizing the B design of services as part of a well-defined service inventory, one of our primary objecU tives is to avoid having to resort to data transformation wherever possible. Data transformation introduces a number of problems, including: • increased integration development effort required to create the mapping logic • increased performance overhead resulting from the need to execute the mapping logic at runtime with every data exchange SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 141 141 6.4 Contracts and Service Design • increased architectural complexity due to the incorporation of transformation layers • increased governance burden due to the need to maintain and evolve transformation layers along with the rest of the architecture The consistent application of data representation standards avoids these issues by keeping service contract data models in alignment, as illustrated in Figure 6.10. W I L S O N , J A M I E 5 0 5 1 B U Figure 6.10 By increasing the standardization of service contracts and the resulting message data representation, the quantity of required transformation layers is reduced. This results in more efficient and simplified interoperability, as shown in this diagram where runtime message transformation is avoided when two services share data based on a common XML schema. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 142 6/13/07 4:46 PM Page 142 Chapter 6: Service Contracts (Standardization and Design) While transformation avoidance via data representation standardization is feasible within a controlled environment, it is often more challenging when sharing data between organizations. The use of industry schemas or an unwillingness for organizations to agree on the same schema predictably leads to the need for data transformation. A foreknowledge of these issues places even more emphasis on successfully realizing this principle within organization boundaries so that the overall impact and burden of transformation layers can be mitigated. W I Although this chapter emphasizes data transformation avoidance, it is worth noting that the standardization of service contractsLcan also overcome other forms of undesirable transformation layers, such as S the use of proprietary adapters and bridging products used to translate disparate communication protocols. O N Standardization and Granularity The use of design standards can impact all four, types of service-related design granularity. NOTE Service-level granularity is impacted and often determined by the choice of service J model. Basing functional context on service models is, in fact, a form of standardization in itself. A service based on the entity service A model, for example, will inherit a predefined functional scope that will determine M the overall measure of service granularity (as shown in Example 6.4). ... ... ... ... ... ... I E 5 0 5 1 B U Example 6.4 A standardized WSDL definition representing an Invoice service will likely have a predetermined functional scope associated with a range of invoice-related processing. The result is a coarse level of service granularity. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 143 143 6.4 Contracts and Service Design While capability granularity is often initially defined when carrying out the service modeling process (see Appendix B), design standards derived from or based on design patterns concentrated on the service contract will often further shape the granularity of a capability or add capabilities with different granularity levels. Data granularity can also be directly defined by data representation standards and further affected by architectural design standards concerned with regulating message sizes and service-roundtrips for scalability and performance reasons. Example 6.5 shows how W standardization affects both the capability and data granularity of two operations. ... ... I L S O N , Example 6.5 Design standards may require a combination of coarse and fine-grained service capabilities. In this example, the Update operation receives an entire invoice document as input and updates any changed values. As a result, both capability and data granularity are coarse. The finer-grained UpdateStatus operation receives a status value as input and is only responsible for updating that value. This would represent fine-grained capability and data granularity. J A M Finally, constraint granularity is often directly dictated by a series of detailed design I standards. These are usually validation-centric conventions that specify how flexible constraints may be (in terms of allowing ranges E of input or output data values) and how, specifically, the constraints themselves are to be expressed. Incorporating pre-determined code values5into data types, for example, can dramatically increase constraint granularity (as shown in Example 6.6). On the other hand, when 0 working with policy definitions, the use of policy alternatives and the application of the 5 can introduce some “validation leeway” wsp:optional and wsp:ignorable attributes 1 constraints. and can therefore lead to more coarse-grained B U Example 6.6 An example of a very fine-grained constraint using standardized single character codes to represent pending (“P”) and approved (“A”) status values. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 144 6/13/07 4:46 PM Page 144 Chapter 6: Service Contracts (Standardization and Design) Design standards may furthermore determine the quantity and type of validation logic that should be located in the service contract. For example, there may be a design standard that requires validation logic associated with business rules to be carried out within the underlying service logic—not within the service contract. While the overall amount of validation logic remains the same, the application of this particular design standard would result in coarser-grained constraint granularity because this form of granularity is concerned with the contract only. W I Models Standardized Service Contracts and Service L us with templates for common types As we learned in Chapter 3, service models provide of services. The two models that boast high reuse S potential are entity and utility services. Contracts for these service types receive a great O deal of attention in that they are highly streamlined and tuned so as to facilitate numerous usage scenarios. N Task services are often delivered to represent just a single task. This reduces the chances , of them being shared, thereby also reducing the need to optimize the contract beyond the immediate requirements the service is being delivered for. Similarly, orchestrated J task services (responsible for encapsulating business process logic hosted by orchestration platforms) also require contracts that are more specific to the process logic they A represent. M Another characteristic that distinguishes process-agnostic from process-specific services I is the average size of the contracts they tend to establish. Because agnostic services need E to provide a range of generic functionality, they are usually equipped with several finely tuned capabilities. Process-specific services, on the other hand, sometimes require only 5 a single capability that allows an external service consumer to “kick-off” the process logic they encapsulate. 0 Regardless of the nature of the logic represented 5 by these service models, all benefit from being subjected to the same set of design standards and naming conventions to what1 ever extent feasible. B U How Standardized Service Contract Design Affects Other Principles With an insight into how principles inter-relate, we can gain a better understanding of how to optimize service designs. Let’s begin with a look at the principles that directly relate to the standardization and overall design of service contracts (Figure 6.11). SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 145 145 6.4 Contracts and Service Design W I L S O N , J A Figure 6.11 The manner in which service contracts are designed directly M affects the extent to which some of the most important service-orientation principles can be realized. I Standardized Service Contract and Service Loose E Coupling A service consumer program is designed specifically to comply with the technical interface requirements dictated by the contract of the service it will be binding to, creating a 5 very real dependency between consumer and service. 0 As explained in Chapter 7, the principle of Service Loose Coupling emphasizes that 5 services should be designed to have minimal dependencies on other services. By limit1 contract, a reduced amount of overall couing cross-service dependencies to the service pling is attained between the solution logic B encapsulated by each respective service. This is one of the primary goals of the Service U Loose Coupling principle. To fully achieve this goal requires that we pay special attention to the content and design of each service contract. Even though a loosely coupled relationship may have been formed between a service and its consumers, there are degrees of “looseness” that can be attained. Specifically, the more detailed and content-rich a technical service contract is, the greater the dependency consumers will form on the service. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 146 6/13/07 4:46 PM Page 146 Chapter 6: Service Contracts (Standardization and Design) From an architectural perspective, it is often desirable to defer lots of detail to the service contract layer. In a Web service, for example, numerous validation constraints, complex type constructs, and detailed policy assertions can be placed in WSDL, XML schema, and WS-Policy definitions. This guarantees two important results: First, that the service contract will be very communicative to those who need to develop potential service consumer programs, and secondly, that the service itself can be designed to process a very predictable set of data. W Although from a service developer’s perspective this all makes sense, the principle of I us to reconsider. Chapter 7 explores the Service Loose Coupling pushes back and asks details of this dynamic, but for the purpose ofL this chapter, it is important to understand that the extent of loose coupling that is achieved S between two services is directly tied to the quantity of dependencies placed into the service contract. It is therefore during the O design of the contract that cross-service coupling is determined. N A side note to this discussion is the fact that contracts that are standardized will tend to , improve the consistency and quality of coupling between services. An exception to this is when the standards themselves impose an increased quantity of contract content. This can happen inadvertently when multiple design J standards are created independently and their collective effect is not considered. A M Standardized Service Contract and Service Abstraction I As with Service Loose Coupling, this principle encourages us to limit what is expressed in the service contract. In fact, abstraction asksEus to streamline the contract to the extent that all non-essential information about a service is hidden. 5 levels at which it can be applied are The details of Service Abstraction and the different covered in Chapter 8. From the perspective of0a service designer, it is important to note that what is documented in the service contract may very well be the only piece of infor5 mation available to describe its purpose, capabilities, and interaction requirements. 1 Therefore, there is a tendency to put more information into the contract to ensure that its B meaning is correctly understood and it is properly utilized. While this may seem to run U that encourages us to minimize concontrary to the Service Loose Coupling principle tract content, it simply emphasizes the need for balanced contract design. In other words, it is again the design of the service contract that determines the extent of abstraction. The more detail in the contract, the less information about the service is abstracted. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 147 147 6.4 Contracts and Service Design Standardized Service Contract and Service Reusability The principle of Service Reusability is often focused on the logic encapsulated by the service. If this logic is sufficiently generic and common, the service can be classified as reusable. However, it comes down to how the service contract is designed that determines how reusable solution logic relates to data exchange. As established in Chapter 9, there are different levels of reuse attainable by a service. Because we want reusable services to beW as agnostic as possible to parent business processes and tasks, the underlying service logic often needs to include a series of highly I generic routines capable of processing a range of message content. L Keeping the overall service design more reusable therefore implies that constraints on S the contract layer be lifted so as to allow a wider range of input and output data to be processed. It also places an emphasis onO designing extensible contracts so that as a reusable service matures, new capabilities can N be added without compromising existing consumer dependencies (in other words, without requiring a new version of the contract , to be released). What all of this amounts to is the fact that service contract design can indeed affect the J extent to which a service can be reused. Essentially, the more generic, flexible, and extensible a contract is, the greater the long-termAreuse potential of the service. M Standardized Service Contract and Service Discoverability I If a service can’t be found or if its capabilities E aren’t clearly understood, opportunities for the service to be utilized will likely be missed. Discoverability mechanisms, such as service registries, provide a means of locating service contracts. Often, though, contracts 5 be “dug out” from a remote folder or direcare simply published somewhere or need to 0 for and assessing reusable services within tory on a LAN. Either way, when searching the enterprise, it is imperative that what the 5 contract represents is clearly documented and communicated. 1 Although the clarity of contracts can be improved by adding human-readable annotaB tions, formal standardization plays a key role in making a contract more easily interU pretable. The more consistently contracts are labeled and structured, the more predictable they become to those who need to use them. A strong naming convention, for example, can immediately convey the purpose and requirements of individual capabilities belonging to a service you may have never seen SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 148 6/13/07 4:46 PM Page 148 Chapter 6: Service Contracts (Standardization and Design) before. Furthermore, the aforementioned use of standardized policy assertion vocabularies can also improve the communication quality of service contracts when optional or ignorable assertions are used to hint at behavioral service characteristics or preferences. Chapter 12 is dedicated to discussing the importance of making services discoverable. Here, we just want to establish that the design characteristic of discoverability is directly tied to the content of the service contract. The more standardized a contract is and the more the technical interface details are supplemented with meta information, the more W discoverable the service will become. I Standardized Service Contract and Service Composability L As discussed in Chapter 13, individual services S need to be capable of acting as effective composition members in order for a serviceO inventory to facilitate repeated compositions in support of fulfilling a wide range of automation requirements. N From a contract design perspective, this means viewing the service from two perspectives: , • as though it will be accessed by just one consumer to perform a specific task • as though it will be accessed by a consumer J that is coordinating the service’s involvement as part of a larger composition A These two scenarios may seem identical to theM service (it is still just one consumer invoking the service), but the circumstances often introduce different interaction requirements. I Note that Service Composability requirements Efrequently relate to the granularity with which the service contract expresses its capabilities. Coarse-grained capabilities, for example, are usually structured to receive larger, more complete documents and to 5 respond with the same. While this saves on roundtrips, it can also introduce extra band0 of the data being exchanged is actually width and processing demands because not all necessary for the capability to carry out its task. 5 Therefore, overly coarse-grained capabilities 1 are often less suitable for when the service needs to participate in a larger composition. This B means alternative design characteristics may have to be provided, even if they result in a degree of interface redundancy or U specificity. Several design patterns can be used to address this issue, in particular the Contract Denormalization pattern. There are many issues that affect the ultimate composability of a service. Service contracts can certainly play a significant part in supporting or hindering the realization of this principle. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 149 6.5 Risks Associated with Service Contract Design 149 SUMMARY OF KEY POINTS • Both the quantity of service contract content and the extent to which it is standardized have a direct bearing on how other design principles can be realized. • This design principle has especially close relationships with the Service Loose Coupling and Service Abstraction principles. W 6.5 Risks Associated with Service Contract Design I The stage at which the design of a service contract is determined is considered a critical L decision point in service delivery projects. In fact, entire service-oriented analysis and S service-oriented design processes have been developed solely to provide a series of forO that go into finalizing the service contract. mal steps, each of which raises considerations As a result, there are several pitfalls that lieNbetween the idea for a service and its even, at some of the primary risks associated tual concrete expression. Here we take a look with designing the contract and then implementing the service based on that design. All of these risks essentially come down to the level of judgment exercised by the contract J designer. A M Versioning I One of the most challenging aspects of managing service-oriented enterprise environE contracts. Once an implemented service ments is dealing with the evolution of service has been in use for some time, it is likely that several dependencies will have been formed on it by service consumers. This is 5 generally tied to the reuse potential of the service—essentially the more reusable its underlying logic, the greater the volume and 0 frequency with which programs that need to consume it will be built. 5 Service reuse is a positive and planned dynamic of SOA, but it does result in an increas1 ing amount of enterprise-wide coupling being placed onto a single service contract. This B to be appropriately balanced and extensiamplifies the need for the design of a service ble because once it is implemented, significant U changes that can effectively “break” the established contract may introduce the need for new service versions to be released. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM 150 Page 150 Chapter 6: Service Contracts (Standardization and Design) NOTE Much of service-orientation is geared toward producing services with long life-spans. In fact, longevity, is a highly desirable design characteristic of service contracts and is also a measurable success indicator as to how well service-orientation was originally applied. If new versions of service contracts need to be released on a regular basis, it is often an indication that principles related to composability, reuse, and coupling were not given sufficient attention. Note that the book SOA: Design Patterns W provides several patterns that address versioning concerns, and the Web Service Contract Design for SOA I title (described in the More About Service Contracts section) has a chapter L for Web service contracts. dedicated to versioning techniques specifically S O There are options when it comes to choosing an implementation technology for services. N For example, services can be built using different programming languages and devel, provides a valid approach to building opment platforms. An implementation option Technology Dependencies SOA as long as the underlying technology is capable of realizing a significant extent of service-orientation. J Both open and proprietary technologies areA available in the SOA marketplace. Nonindustry standard approaches usually involve the utilization of component-based M systems with RPC technology augmented to support service-orientation. Industry stanI dard technologies generally refer to the Web services platform and its non-proprietary E necessitate the use of WS-I compliant communications framework (which may also service contracts). 5 implemented using some form of techBecause service contracts need to be physically nology, there is a risk associated with the maturity 0 and lifespan of the technology itself. Once the contract is in place, it establishes itself as the sole entry point into the service’s 5 encapsulated functionality. If new, enhanced technology platforms emerge the existing 1 service contract can become outdated, not because of the solution logic it is representB can communicate is subject to a noning, but because the medium by which the service backwards-compatible upgrade. U BEST PRACTICE Steps can be taken to mitigate this risk when designing solution logic (proprietary or otherwise) capable of encapsulation via Web services. As per fundamental service design patterns, service contracts can be designed according to existing conventions so that if a Web service contract needs to later be derived, it will mirror a technical interface that is already standardized. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 151 6.5 Risks Associated with Service Contract Design 151 Development Tool Deficiencies Service contracts themselves can’t be ignored because we need them to create services. However, the design of service contracts can certainly be neglected. Depending on the implementation platform used to realize services, it is often easy to allow a development tool to derive and auto-generate the contract from an arbitrary source, such as a database or a programmatic interface. This feature has led to the creation of many nonstandardized Web service contracts. W We can avoid the problems associated with auto-generated contracts by introducing I standards that require that service contracts be custom-designed. A potential challenge L ability of development tools to accept and to accomplishing this, though, lies with the preserve the custom contract content after S the developer proceeds to build the supporting service logic. O Some Web services development tools, for N example, offer limited support for importing custom-coded WSDL and XML schema definitions. Even if they can be imported, the , program may attempt to alter some of the code or may raise errors because it does not support the full range of WSDL and XML schema features. Further limitations may be J and then import WS-Policy definitions. encountered when attempting to customize A BEST PRACTICE M When building services as Web services, it Iis worth taking the time to assess the marketplace. Commercial tools have different features and limitations as to the amount of E support and control they offer for customizing the actual Web service markup code. Some of the key considerations to look out for include the following: 5 • It can be very helpful to have the option to view service contracts graphically so as 0 to display a tree view of the various element constructs. Although this feature is common, it varies in sophistication. For5example, it is preferable to be able to view a WSDL definition in relation to numerous1external schema definitions on one screen. • All tools provide some sort of validationB checking. However, the quality of feedback can vary. It can be invaluable to the contract designer for the tool to provide highly U descriptive error and warning messages that naturally incorporate WS-I basic profile checking. • To properly apply detailed contract design standards requires the ability to fully customize the contract markup code. Some tools have limitations as to the range of support they provide for Web services specifications. This can cause problems in that the tool may not be able to properly validate the code or may actually modify it. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 152 6/13/07 4:46 PM Page 152 Chapter 6: Service Contracts (Standardization and Design) • Some tools may provide little to no support for service contracts that include WSPolicy definitions. There may be development environments that assume you want to create policies only through graphical user interfaces. It is therefore a good idea to investigate whether custom coded policies can be imported along with other service description documents. NOTEW I to avoid the use of Web servThis book repeatedly emphasizes the need ice contract auto-generation features. The L intent is not to state that these features represent poor product design. In fact, auto-generation utilities S helped popularize Web services by making their development easier. Odesign, their use is generally However, when pursuing service-oriented limited due to contract standardization requirements. N , SUMMARY OF KEY POINTS • The quality of the initial release of a service contract often determines its ultiJ sooner it needs to be changed in mate longevity within a given enterprise. The a non-backwards-compatible manner, the sooner version control enters the A picture. M • Service-orientation can be applied to proprietary components and Web servI types of services co-exist within ices. Either is a valid option, but having both the same inventory can lead to interoperability E issues due to different communications standards and technologies. • A desired level of standardization can be inhibited by development tools inca5 pable of properly importing and preserving custom designed service contracts. 0 5 1 6.6 More About Service Contracts B Provided in this section are some supplementary notes and resources regarding the U design of standardized service contracts. Non-Technical Service Contract Documents At the beginning of this chapter it was established that a service contract typically consists of a collection of technical service descriptions, but that it can also include nontechnical documents. A classic example is the service level agreement (SLA), a document SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc. 08_0132344823_06.qxd 6/13/07 4:46 PM Page 153 153 6.6 More About Service Contracts that establishes a contract associated with quality of service characteristics, such as availability, accessibility, and performance. Though not technically binding, this agreement is often legally binding and therefore considered an important extension of the technical interface. An SLA can provide additional semantic details about a service, thereby reducing its level of abstraction while preserving (or perhaps even enhancing) the existing level of required technical coupling. W I guaranteed availability schedule L guaranteed response times for service S capabilities O response time averages for service capabilities N usage statistics (concurrency and variance of service consumers) , Some examples include: • • • • • a rating based on feedback from service consumer owners • charge-back costs (which may be required if the service is a third-party product or J part of an infrastructure department that charges project teams for its usage) A • coupling, reusability, autonomy, statelessness meta details (as explained in M Chapters 7, 9, 10, and 11) I Note that the service profile document described in Chapter 15 can be used to collect E various types of information during the definition and development of a service that can later be carried over into the SLA. 5 “Web Service Contract Design for SOA”0 The purpose of this chapter is to establish standardized service contract design as a core 5 and governing principle that shapes a fundamental part of the service-orientation para1 digm. The focus has therefore been on the influence of this principle and conceptual topB ics associated with the positioning and utilization of service contracts. U This book has deliberately not delved into the specific technical details of designing WSDL, XML schema, and WS-Policy definitions for Web services to avoid overlap with Web Service Contract Design for SOA, a separate book in the Prentice Hall Service-Oriented Computing Series from Thomas Erl. This title is dedicated to exploring the details of designing Web service contracts and supplies examples based on the use of WSDL, XML schema, SOAP, WS-Policy, and WS-Addressing. SOA Principles of Service Design, First Edition, by Thomas Erl. Published by Prentice Hall. Copyright © 2008 by Pearson Education, Inc.
Purchase answer to see full attachment