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