Service design guidelines

Incorporating service-oriented design principles into formal standards is critical to the success of SOA within an organization. Provided in this section is a set of guidelines that can be used as a starting point from which you can derive your own standards.

15.5.1. Apply naming standards

Labeling services is the equivalent to labeling IT infrastructure. It is therefore essential that service interfaces be as consistently self-descriptive as possible.

Naming standards therefore need to be defined and applied to:

• service endpoint names
• service operation names
• message values

Existing naming conventions vary by organization. Some employ OO naming standards where objects are assigned nouns and methods are labeled with verbs. Others simply apply verbs to both components and their methods. Although it would be very useful, there is no perfect naming standard for all organizations. The key is that whatever standards you choose must be implemented consistently throughout all service-oriented solution environments.

Here are some suggestions:

• Service candidates with high cross-application reuse potential should always be stripped of any naming characteristics that hint at the business processes for which they were originally built. For example, instead of naming an operation GetTimesheetSubmissionID, simply reduce it to GetTimesheetID or just GetID.
• Application services need to be named according to the processing context under which their operations are grouped. Both the verb+noun or noun only conventions can be used. Simplified examples of suitable application service names are CustomerDataAccess, SalesReporting, and GetStatistics.
• Application service operations need to clearly communicate the nature of their individual functionality. Examples of suitable application service operation names are GetReport, ConvertCurrency, and VerifyData.
• Entity-centric business services need to remain representative of the entity models from which their corresponding service candidates were derived. Therefore, the naming conventions used must reflect those established in the organization's original entity models. Typically, this type of service uses the noun only naming structure. Examples of suitable entity-centric business service names are Invoice, Customer, and Employee.
• Service operations for entity-centric business services should be verb-based and should not repeat the entity name. For example, an entity-centric service called Invoice should not have an operation named AddInvoice.

15.5.2. Apply a suitable level of interface granularity

As evidenced by the case study examples in this chapter, the granularity at which services can be designed can vary. The trend to create interfaces for Web services that are coarser than those traditionally designed for RPC-based components has been encouraged by vendors as a means of overcoming some of the performance challenges associated with XML-based processing.

Performance, of course, is critical to the success and ultimate evolution of service-oriented solutions. However, other considerations also need to be taken into account. The coarser the granularity of an interface, the less reuse it may be able to offer. If multiple functions are bundled into a single operation, it may be undesirable for requestors who only require the use of one of those functions. Additionally, some coarse-grained interfaces may actually impose redundant processing or data exchange by forcing requestors to submit data not relevant to a particular activity.

Service interface granularity is a key strategic decision point that deserves a good deal of attention during the service-oriented design phase. Here are some guidelines for tackling this issue:

• Fully understand the performance limitations of the target deployment environment and explore alternative supporting technologies (such as the binary encoding extensions developed by the W3C), if required.
• Explore the possibility of providing alternate (coarse and less coarse-grained) WSDL definitions for the same Web services. Or explore the option of supplying redundant coarse and less coarse-grained operations in the same WSDL definition. These approaches de-normalize service contracts but can address performance issues and accommodate a range of requestors.
• Assign coarse-grained interfaces to services designated as solution endpoints and allow finer-grained interfaces for services confined to predefined boundaries. This, of course, runs somewhat contrary to service-orientation principles and SOA characteristics that promote reuse and interoperability in services. Interoperability is promoted in coarse-grained services, and reusability is more fostered in finer-grained services. One could standardize a composition model that requires coarse-grained services to act as controllers and endpoints for finer-grained services.

Regardless of your approach, ensure that it is consistent and predictable so that an SOA can meet performance demands while remaining standardized.

Case Study

TLS chose an approach to interface granularity where services positioned for use by requestors outside of TLS would provide consistently coarse-grained interfaces. Operations on these services would accept all of the data required to process a particular activity. Further round-trips between external requestor and the service would only be required if absolutely necessary or if internal policies demanded it.

Services used within TLS could provide less coarse-grained operations to facilitate reuse and a broader range of potential (internal) requestors, as long as the processing overhead imposed by less coarse-grained operations was acceptable.

 

15.5.3. Design service operations to be inherently extensible

Regardless of how well services are designed when first deployed, they can never be fully prepared for what the future holds. Some types of business process changes result in the need for the scope of entities to be broadened. As a result, corresponding business services may need to be extended. While service characteristics such as reusability and composability are thought through when partitioning logic as part of the service modeling process, extensibility is more of a physical design quality that needs to be considered during design.

Depending on the nature of the change, extensibility can sometimes be achieved without breaking the existing service interface. It is important to design operations and messages to be as activity-agnostic as possible. This supports the processing of future non-specific values and functions that are still related to the operation's or message's overall purpose. Further, it is a good habit to respond to new processing requirements by first investigating the possibility of composing other available services (including services that can be purchased or leased). This may succeed in fulfilling requirements without having to touch the service interface.

Note that extensions to an existing service interface will impact the corresponding XSD schema. These extensions can be facilitated by supplying new schemas specifically for the extension. Before going down this road, though, ensure that established version control standards are firmly in place.

Case Study

Due to the size of the TLS corporation, it is not uncommon for employees to be reallocated or to seek vertical or lateral position changes. The latter scenario is made further common by the "promote from within" motto encouraged by many divisional directors.

When an employee changes position or rank, the employee is expected to update his/her own profile using a form on the local intranet. Because this step is voluntary, it is often never performed. This, predictably, results in an increasingly out-of-date set of profiles. To counter this trend, the TLS Timesheet Submission Process is altered to include an employee profile verification step. Once implemented, it will verify profile information prior to accepting a timesheet. Timesheets submitted by employees with invalid profiles will simply be rejected.

To implement this new requirement, the Timesheet Service interface is not altered. Instead, the underlying service logic is extended to incorporate a separate application service that performs the profile verification.

 

15.5.4. Identify known and potential service requestors

Services are almost always built as part of the delivery of a specific automation solution. Therefore, they are designed to address business requirements as they pertain to that application. Limiting a service design to fulfill immediate requirements can inhibit its potential as a reusable, adaptive, and interoperable unit of processing logic.

It is therefore advisable that any existing service design process incorporate a speculative analysis of how that service may be utilized outside its initial application boundaries. In other words, it can be useful and practical to identify any potential future service requestors and to then incorporate their anticipated requirements into the current service design.

This can lead to additional functional requirements, which may or may not be desirable, depending on the current project scope, budget, and other related constraints. More importantly, though, this can lead to design refinements that may not significantly impact the current project at all. For example, it may be possible to adjust the granularity of service interfaces at the design stage without much impact to the overall project.

15.5.5. Consider using modular WSDL documents

WSDL service descriptions can be assembled dynamically at runtime through the use of import statements that link to separate files that contain parts of the service definition. This allows you to define modules for types, operations, and bindings that can be shared across WSDL documents.

It also allows you to leverage any existing XSD schema modules you may already have designed. Many organizations separate schemas into granular modules that represent individual complex types. This establishes a centralized repository of schemas that can be assembled into customized master schema definitions. By enabling you to import XSD schema modules into the types construct of a WSDL definition, you now can have your WSDL documents use those same schema modules.

Note

Incidentally, the WS-I Basic Profile requires that when designing modular WSDL definitions, the import statement be used to import other WSDL definitions or XSD schemas.

Case Study

TLS considers importing the bindings construct so that it can be reused and perhaps even dynamically determined. However, it is later decided to leave the bindings construct as part of the WSDL document. Here is the import statement used to carry out this test:

Example 15.22. An import element used to pull in the bindings construct residing in a separate file.

 

15.5.6. Use namespaces carefully

A WSDL definition consists of a collection of elements with different origins. Therefore, each definition often will involve a number of different namespaces. Following is a list of common namespaces used to represent specification-based elements:

• http://schemas.xmlsoap.org/wsdl/
• http://schemas.xmlsoap.org/wsdl/soap/
• http://www.w3.org/2001/XMLSchema/
• http://schemas.xmlsoap.org/wsdl/http/
• http://schemas.xmlsoap.org/wsdl/mime/
• http://schemas.xmlsoap.org/soap/envelope/

When assembling a WSDL from modules, additional namespaces come into play, especially when importing XSD schema definitions. Further, when defining your own elements, you can establish more namespaces to represent application-specific parts of the WSDL documents. It is not uncommon for larger WSDL documents to contain up to ten different namespaces and the qualifiers to go along with them. Therefore, it is highly recommended that you organize the use of namespaces carefully within and across WSDL documents.

The WS-I Basic Profile requires the use of the targetNamespace attribute to assign a namespace to the WSDL as a whole. If the XSD schema is embedded within the WSDL definition, then the WS-I Basic Profile requires that it also be assigned a targetNamespace value (which can be the same value used by the WSDL targetNamespace).

Case Study

Some of the common namespaces identified earlier are not required by the TLS Employee Service and therefore are omitted from the list of definitions attributes. A targetNamespace is added, along with two namespaces associated with the two imported schemas.

Example 15.23. The namespace declarations within the definitions element of the TLS Employee.wsdl file.

targetNamespace="http://www.xmltc.com/tls/employee/wsdl/"
 xmlns="http://schemas.xmlsoap.org/wsdl/"
 xmlns:act=
 "http://www.xmltc.com/tls/employee/schema/accounting/"
 xmlns:hr="http://www.xmltc.com/tls/employee/schema/hr/"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:tns="http://www.xmltc.com/tls/employee/wsdl/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 ...

 

15.5.7. Use the SOAP document and literal attribute values

There are two specific attributes that establish the SOAP message payload format and the data type system used to represent payload data. These are the style attribute used by the soap:binding element and the use attribute assigned to the soap:body element. Both of these elements reside within the WSDL binding construct.

How these attributes are set is significant as it relates to the manner in which SOAP message content is structured and represented:

• The style attribute can be assigned a value of "document" or "rpc." The former supports the embedding of entire XML documents within the SOAP body, whereas the latter is designed more to mirror traditional RPC communication and therefore supports parameter type data.
• The use attribute can be set to a value of "literal" or "encoded." SOAP originally provided its own type system used to represent body content. Later, support for XSD data types was incorporated. This attribute value indicates which type system you want your message to use. The "literal" setting states that XSD data types will be applied.

When considering these two attributes, the following four combinations are possible and supported by SOAP:

• style:RPC + use:encoded
• style:RPC + use:literal
• style:document + use:encoded
• style:document + use:literal

The style:document + use:literal combination is preferred by SOA because it supports the notion of the document-style messaging model that is key to realizing the features of many key WS-* specifications. Further, the WS-I Basic Profile requires that the use attribute always be set to "literal."

Case Study

In building the concrete part of the Employee Service interface definition, TLS architects decide to use the style:document + use:literal combination, as shown here:

Example 15.24. The binding construct of the TLS Employee.wsdl document.

 

15.5.8. Use WS-I Profiles even if WS-I compliance isn't required

If WS-I compliance is not on your list of immediate requirements, it still is recommended that you consider using the many standards and best practices provided by the Basic Profile document. They are sound, well researched, and proven and can save you a great deal of time and effort when developing your own design standards.

Note

Another WS-I deliverable we have not covered in this book is the Basic Security Profile, which governs and standardizes the use of security-related specifications for interoperability purposes. Visit www.ws-i.org for more information.

 

15.5.9. Document services with metadata

As evidenced by the discussions we had about WS-Policy and WS-MetadataExchange in Chapter 7, the WS-* platform is placing an ever-increasing amount of emphasis on the quality and depth of service descriptions. It won't be uncommon, though, for many SOAs to exist without the benefit of a technical environment capable of supporting service description content beyond that provided by WSDL definitions.

Policies in particular represent an important metadata supplement to WSDL definitions. For example, a policy may express certain security requirements, processing preferences, and behavioral characteristics of a service provider. This allows service requestors to better assess a service provider and offers them the opportunity to be fully prepared for interaction.

Polices are formally implemented using a set of WS-* specifications described in Chapter 7. Regardless of whether these specifications actually are used in an organization, policy information should still be documented as part of any service design. This not only provides developers building service requestors for a given service provider a great deal of useful information, it also accommodates an eventual move to when policies become a common part of service-oriented architectures.

Whatever unique properties a service has, they should be documented to easily communicate a service's requirements, characteristics, or restrictions to others that may want to use it. This information can be added to a WSDL definition through the use of the documentation element and it could even be contained within a metadata document that is published separately and easily accessible. This promotes the discovery and reuse of services. When possible, this documentation also can be physically attached to electronic modeling diagrams.

Note

If you are designing WS-I compliant services, you can improve the quality of your service description metadata by attaching WS-I conformance claims. These advertise compliance to specific WS-I profiles. See www.ws-i.org for more information.

SUMMARY OF KEY POINTS

• The design of a Web service needs to achieve a balance between meeting requirements expressed in the service candidate models and those imposed by real-world considerations.
• Starting the service design with the creation of a WSDL definition is a recommended approach to building quality services that adhere to existing interface design standards.