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 24×7?
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.
