*/<<Introduction/*
Service-Oriented Architecture (SOA) is a highly /collaborative/
paradigm, and attempts to break down the invisible barriers between IT
and business. A critical step to be undertaken when implementing a SOA
is to identify, specify, catalog and document candidate services. Given
the sheer complexity of the task, this is more of an art, rather than a
science. However, there do exist some common-sense principles and best
practices for this purpose. These techniques ensure /consistency/ and
more importantly, /repeatability/ in the process, so that it can be
applied holistically across the enterprise. This paper specifies one
such technique.
Central to this technique is a /service design template/, presented in
terms of a simple questionnaire, for designing, specifying and
documenting a service contract. A service contract is a comprehensive
description of not only the business functionality provided by the
service, but also the technical design of the service along with
specifications governing its usage, call semantics, service level
declarations and key performance indicators (KPIs).
The over-arching goal of a service contract description document should
be to develop and catalog a /uniform/ yet multi-dimensional,
/enterprise-wide/ understanding of the purpose, scope and representation
of what this service entails and involves.
*/Audience and Participation
/*It is visualized that the questions in this template are debated,
discussed and "filled in" by cross-functional teams, intended to be
composed of /Requirements Analysts, Business Analysts, Software
Architects, Developers, Management stakeholders and Operations
representatives./ A cross-functional team participation is deemed
essential to designing a service contract, as a complement to the
collaborative effort discussed before.
It must be noted that this article proposes the */same/* document
template to be utilized, iteratively, by team members with different
interests and/or expertise. Design methodology gurus will recognize this
to be a marked departure from traditional "waterfall" approaches, where
/requirements gathering and design/ activities were silo-ed and
functionally separate, hence requiring entirely different documents.
Consequently, methods had to be devised where these documents needed to
be "linked" together. This often lead to these teams working at
cross-purposes with each other, and critically, essential details of the
functionality implementation are lost in linking and translation.
In the new approach to service design, the "requirements-gathering" and
"design" activities are visualized as /concurrent/ activities,
proceeding hand-in-hand. The resulting knowledge accumulated in these
efforts is collected and collated into a single artifact (the service
design document), which progressively and cumulatively gets richer in
content, and endeavors to answer to all parties involved. In the end,
what emerges is a comprehensive, detailed document describing the
service and its features.
The idea is to promote and enforce a sense of
"everybody-on-the-same-page" assuredness, even before the implementation
of the service is undertaken. This promotes business and technology
participation and ownership in equal measure (a key goal of SOA), and
enhances the likelihood that the implemented service is actually
delivered and adds value to the enterprise.
*/Service Contract Design Template/*
*What is the responsibility of the service?
*This provides the basic description of why the service should exist. In
other words, this states the basic business scope of the service. A
service "does" something in terms of business significance (in other
words, encapsulates business functionality). This also identifies the
software component/s which implement(s) the service.
*Is the service idempotent?*
In other words, if a call to the service is duplicated, and instead of
being called once, the service is called twice with identical
parameters/payload, will the service detect the duplication and prevent
any effects on the underlying systems? /Risk: The implementation of such
a service will be more complicated./
*What pre-conditions and post-conditions apply to this service?*
Similar to use case development, describe the factors that must be in
place for this service to be used. Describe the behavior of the service
both in the /"happy path scenario"/ as well as when these preconditions
such as state of data (incoming parameters, values discovered during
course of execution, database values etc) are not met. Describe the
limitations and constraints of the service.
*Is the service synchronous or asynchronous?*
This refers to the call semantics of the service -- synchronous or
asynchronous. Justify the case for either choice: is it practical for a
client to wait for the service to respond? If no, there is a case for
asynchronous service.
In case of a synchronous service, what are the implications of client
wait-time? How long should a client wait? What is the acceptable
time-out interval? What are the procedures to be followed after a time-out?
In case of an asynchronous service, the client does not have to wait for
a response, but how will the client be notified of the fact that the
client's request was "serviced"? Is there a notification mechanism?
*Identify the consumers of this service.
*Define the actors and/or roles that a client needs to represent when
calling this service. Are there multiple consumers of this service?
Does this service need to access a centralized repository to
authenticate caller?
Is this service responsible for checking user/role authorizations? This
is a section which caters to the service security implications, beyond
the scope of this article.
What input data elements will be required in order to call the service?
This includes the actual data elements and their format definitions (XSD
elements/Java Types) which the service needs in order to execute
properly. More importantly, it also includes the semantic/business
meaning of each element.
Is there a centralized data dictionary/format library to get these data
elements from?
Will the service have to "transform" the incoming data elements to a
reference, enterprise-wide canonical model?
What data elements will be returned by the service in its
acknowledgement/receipt/return?
Ask the same questions as above (but from an outgoing perspective).
Obviously, this is important from a client's perspective.
Does the service have transactional implications?
Does this service specify/imply a transactional context? In other words,
if errors and exceptions occur during the course of execution of this
service, can the client expect the data to be returned to the original
state?
If this service does specify a transactional context, then is there a
compensatory service which has to be invokes by the client in case of
the original service failure?
When this service is deployed, do we need to plan for and implement the
compensation service, so as to preserve data state integrity?
How do we determine that requirements are met by the service? What are
the KPIs for this service?
This determines and specifies the benchmarks to evaluate whether the
goals for this service were accomplished.
Determine bothh technical and business KPIs for this service. An example
of a technical KPI would be: service performance under peak load
conditions or some such metric. A business KPI example would be: Reduced
order processing turn-around time by 10%.
What are the SLA elements governing this service?
Is there are QoS classification for types of clients?
Will the service be available 24x7?
What is the service level agreement that the hosting team (in our case,
operations) is willing to sign up for?
If service is not available, what is the expected caller responsibility?
How is the service going to be implemented, within existing software
infrastructure?
Every IT organization has existing and legacy assets covering a wide
variety of implementation platforms, ranging from mainframes to modern
distributed applications. Therefore, a brief overview of how this
specific service is going to be implemented, i.e., which of the existing
assets are planned on being used in the service implementation is
necessary.
If entirely new infrastructure/technology is involved, then the cost of
that new paradigm needs to be factored into the overall cost of
implementing the service.>>
You can find this article at:
http://www.soainstitute.org/articles/article/article/service-oriented-architecture-a-service-contract-design-template.html
Gervas
