Standardizing Service Endpoints
by Thomas Erl

Learn how to design service interface definitions that will help you reap the benefits of standardized service-oriented architecture

Published February 2006

Note: Portions of this article assume a basic knowledge of the Web Services Description Language (WSDL). If you are new to WSDL, you may want to read through the online WSDL tutorial.

More than any prior distributed-computing architecture, service-oriented architecture (SOA) demands a consistent commitment to standardization. The broad scope of SOA transition efforts provides an opportunity to incorporate far-reaching standardization in support of attaining a state of homogeneity and federation across different technical platforms within an enterprise.

A Web service created as part of a service-oriented solution is a potential endpoint for whatever business functionality it exposes. Although you may need to limit or control access to some of your services, you can position many others to reach consumers from a wide variety of sources. Doing so in a standardized manner will greatly help evolve a genuine service-oriented enterprise.

This article explains how extra effort spent during the design of service interface definitions can help foster standardized SOA. It explores a series of design conventions for use with WSDL and also takes a brief look at upcoming enhancements in Oracle's SOA platform that support the creation of standardized service endpoints.

The Scope of Service Orientation

The technology platform currently being built around the service-oriented architectural model represents the next stage in the evolution of distributed computing. What underlies and defines SOA, namely the service-orientation design paradigm, will both significantly affect the design of individual units of automation logic (services) and shape the structure of large automation environments that use those services.

The principles promoted by service orientation—such as reuse, interoperability, and federation—will end up having a great influence on how individual enterprise services, solutions, and integrated environments are designed. This design, in turn, shapes how the individual enterprise domains represented by these environments exist, operate, and relate to each other. Although the SOA model allows organizations to blanket foreign and disparate environments with a standardized service interface layer, this key benefit can be achieved only if you implement and enforce the use of standards from the very start.

The Impact of Standards

As with any other framework, technology platform, or architectural model, the governing principles can be abused. There is a greater danger of abuse in the service-oriented computing world, simply because of its potentially broad application scope. If your organization does not yet have a culture of using internal standards and respecting their use, introducing this notion can pose significant challenges.

During the standards development stage, some of your organization's top experts will need to assess the constraints of current environments and balance them against the goals of your strategic SOA initiative as well as the technological and organizational changes brought on by typical transition efforts. You're sure to find that creating standards can consume a significant amount of time and effort and involve a great deal of decision-making.

Once the standards are finalized, their usage needs to be incorporated into the project lifecycle. Persuading people to use standards can sometimes be more challenging than actually creating them. There is often a great deal of resistance to standards, because they are viewed as rules that discourage creativity and impose inflexibility on the development process.

Recalcitrant developers are likely to discover, however, that standards can actually streamline the solution process, by establishing boundaries that keep project team members from having to repeatedly research various design options. This can save a great deal of time during predevelopment project stages and can simplify the overall solution design.

Nevertheless, standards in support of an enterprisewide SOA transition initiative are sure to make impositions on individual projects. The emphasis on reuse, for example, may require extra time and effort in identifying units of automation logic that may be useful outside of the current solution scope.

Conversely, projects may be prevented from adding features when a reusable service already exists. In this case, developers will be forced to incorporate and build their solution around one or more existing services.

These and many other circumstances can lead to the perception that standards in support of SOA unnecessarily burden individual development projects, by adding complexity to the overall solution design and negatively affecting budgets and timelines.

Establishing a Predictable Service-Oriented Enterprise

Standards can be applied at various levels of a service-oriented environment. At the highest level, you can standardize architecture specifications and other types of internal documents, as well as some infrastructure components such as a service registry.

The design standards most often overlooked but critical to achieving successful service orientation are those that apply to individual services.

Their significance is magnified when services are implemented as Web services. The nonproprietary communications framework that underlies Web services broadens the opportunity for the service to be utilized by any part of the enterprise capable of participating as a service requestor. As the inventory of standardized Web services within an enterprise grows, it becomes a powerful means of re-leveraging investments in already developed and deployed services.

Web services provide the foremost means of achieving a standardized SOA today, but to do so, we need to assume ownership of the WSDL definition. The rest of this article explores how service interfaces can be shaped by standards in support of service orientation.

Taking Control of WSDL

The "WSDL first" approach to building Web services essentially preaches that developers should rely less on the autogeneration utilities provided by most development tools and instead manually define service interfaces, by customizing the WSDL definition. The benefit of this approach is the level of control developers have over a service's interface and encapsulated logic.

To understand interface-level standardization, we need to decompose the WSDL definition that constitutes a Web service interface. A WSDL definition is an XML document defined by the W3C WSDL specification and contains abstract and concrete descriptions that formally express both the service interface and the implementation it supports. These are separated to allow you to change implementation details without affecting the characteristics of the message data.

Because concrete definitions are often influenced or defined by the existing technical infrastructure, this article's focus is on the design of the abstract definition, where the following design considerations come into play:

• Service interface granularity - The logic encapsulated by the service is divided up and made available through service operations.
• Service data exchange requirements - Specific messaging requirements are established.
• Service data representation - Data structures and datatypes are defined or referenced.
• Service interface labeling - Naming conventions are applied to the service interface itself.

Figure 1: Areas of the abstract WSDL definition to which standards can be applied

These are some of the primary aspects of abstract definition design that can contribute to the quality and usability of the service as a whole. Let's take a closer look at each.

Service Interface Granularity

Deciding how the underlying logic of a service should be expressed through its public interface can be one of the most challenging parts of service design. This can lead to a great deal of debate within your organization about whether operations should be coarse- or fine-grained.

Fine-grained operations are typically associated with remote procedure calling (RPC)-type communication patterns, where the focus is on the exchange of small amounts of parameter data to complete a specific task. If other tasks need to be performed by the same service, other service operations are simply subsequently invoked. Example 1 shows the "message" and "operation" constructs used to define a fine-grained operation.

Well-known downsides to the fine-grained approach are that message-based invocation of service operations is expensive and that the resulting overhead of transmitting and processing individual messages to complete small subtasks of a larger process can be unreasonable.

A coarse-grained operation exposes a greater range of functionality within a single service invocation. Often this translates into a bundling of various smaller tasks into a single coarse-grained operation so that more can be accomplished by the transmission of one request message, as shown in Example 2.

The upsides to the coarse-grained approach are fewer requestor-to-provider round-trips and fewer corresponding processing cycles. A less desirable consequence is that coarse-grained operations frequently expose more functionality than what is actually needed. As a result, they may request more input values or larger document structures from all service requestors, when only a fraction of the data may actually be related to what some of the requestors need the service to do.

Although it's difficult to standardize on one level of granularity to foster service orientation throughout service designs, a key goal to keep in mind is that your process must achieve a balance of accommodating those projects that offer immediate solutions and those needed for business domain research and speculative analysis. This balance ensures that the service interface achieves a level of granularity that facilitates both current and known upcoming data exchange requirements.

Service Data Exchange Requirements

Once you've decided which operations a service will expose and what logic each will encapsulate, you need to figure out which input and output values the operation requires to perform its work. The complexity of these design decisions is related to the level of interface granularity. Finer-grained operations tend to have simpler data exchange requirements, whereas coarser-grained operations can introduce a variety of input and output data set combinations.

A common tactic for avoiding the problem of coarse-grained operations' requiring the transmission of too much unnecessary data is to use optional parameters. An operation may be capable of performing a variety of related functions, but the functions actually executed are determined by which parameters are received. Correspondingly, the output values returned by the operation can vary, depending on what work it has actually completed.

Although it is practical and extensible, the use of optional parameters should be limited within Web services. Optional parameters can lead to convoluted service interface designs and a myriad of confusing data exchange scenarios. Additionally, the extent to which optional values can be accommodated is often limited by the underlying XML schemas that define the message structures. Standardized schemas that represent established corporate documents may impose rigid data structures.

A related consideration is whether communication with a service operation requires a one-way or two-way data exchange. The RPC era has ingrained the synchronous pattern into many architects and developers, but within a messaging framework, there are often requirements that are better fulfilled by one-way data transfers in support of asynchronous exchange patterns. Carefully spelled-out standards and guidelines will help service designers and developers deal with these issues in a consistent manner.

Service Data Representation

At the heart of any serious WSDL definition is a well-defined XML schema. It is just as important for XML schemas (which define the data structures for the input and output service messages) to be reusable and agnostic in terms of specific business processes or solution environments as it is for the WSDL definitions representing the overall service logic. Building a centralized set of schemas to express cross-cutting information sets—bodies of data used in different solution environments—avoids a great deal of redundant schema design and contributes to a consistent and pure data representation architecture.

In other words, properly standardizing service endpoints requires standardizing underlying XML schema definitions. It's worth noting that XML schemas generally look different when built for specific WSDL definitions (compared to when they are designed by use of existing data models). For example, a schema created specifically for a Web service will tend to incorporate naming that references service request and response messages, as shown in Example 3. On the other hand, elements within an XML schema designed to represent a corporate document will be concerned with that document only (see Example 4).

Introducing schema modeling standards will introduce additional analysis steps, similar to those needed for developing standardized service interfaces. Fundamental to this analysis is the notion that schemas representing data with reuse potential should not be designed for specific Web services unless their reuse capacity is directly tied to the underlying service logic.

Service Interface Labeling

A well-defined service will encapsulate distinct functionality within a clear-cut context. It is usually easier to label such a service, because its purpose and scope have been well thought out in advance. All that remains is to communicate this concisely to potential service requestors.

Services that are not so well defined can pose more of a problem. If the operations expressed by a service are not related through some logical context, it will be challenging to find a name that accurately represents the service's capabilities.

When designing services from the ground up, you will find that it's helpful to categorize them according to a set of preexisting service models. These models already establish a proposed context and boundary within which the service can be modeled. Common service models include application services, entity-centric business services, and task-centric business services. These establish the utility-centric, entity-centric, and task-centric service contexts, respectively. (I explore service models in detail in my book Service-Oriented Architecture: Concepts, Technology, and Design.)

• The utility-centric context is found in application services involving operations that encapsulate cross-cutting functions, such as event logging, exception handling, or notification. These reusable services need to be labeled according to a specific processing context, agnostic in terms of any particular solution environment. For example, a utility service might be named Notify.
• An entity-centric context is established in a business service that represents a specific business entity, such as an invoice or a purchase order. The labeling of entity-centric business services is often predetermined by the entity name. For example, a service may simply be named Invoice or Customer.
• Task-centric contexts are required for services modeled to encapsulate process logic. In this case, the thread that ties together the grouped operations is a specific activity being automated by the service logic. Therefore, the use of verbs in service names is common. For example, a task-centric service may be called GetProfile or ProfileRetrieval, if that accurately represents the task's scope.

As with service names, labeling individual service operations is also a process that should be subject to standards and guidelines and for which there are already several best practices.

For example, the naming of the service itself ought to influence how the individual operations are labeled. Because a good service name will already clearly establish a meaning and a context, operation names should be streamlined to avoid the use of redundant wording. Take an operation that retrieves invoice history data for a service named Invoice. This operation does not need to be labeled GetInvoiceHistory, because the invoice context is already established by the service name. GetHistory would be sufficient.

Another consideration for labeling operations is the potential reusability of the logic encapsulated by the operation and the service itself. If there is reuse potential, names that tie the operation's functions to a particular activity or task should be avoided. In other words, it is often wise to choose generic operation names to foster future reuse opportunities. For example, it may be appropriate to reduce an operation initially named GetCurrentWidgetPrice to GetCurrentPrice or even just GetPrice.

Naming conventions may seem trivial at first, but as your service inventory grows, so will the potential to reuse, releverage, and achieve integration channels with individual services. In larger organizations, this means that more and more architects, analysts, and developers are discovering and then incorporating foreign services within their solution designs. The effort required to establish a consistent level of clarity across all service endpoints pays off quickly when interoperability and reuse opportunities are more easily recognized and seized.

Standardized Service Endpoints and the Oracle SOA Platform

Oracle has helped shape the Web services technology landscape that has been evolving over the past few years, with contributions to various technical committees and through the implementation of Web services technologies such as Oracle BPEL Process Manager.

Oracle has also publicly supported the industrywide transition to an SOA-based computing platform. Oracle's recognition of the need to empower solution developers with the ability to standardize service endpoints was recently evidenced when it announced support for the WSDL-first development approach in Release 3 of Oracle JDeveloper 10g. In addition to providing more autogeneration and wizard-driven features that developers have become accustomed to, this version also supplies a WSDL editor. Web services can now be designed, as opposed to derived, thereby increasing the control required for achieving standardized SOA.

A Long-Term Proposition

Standardizing SOA endpoints is an ongoing process requiring significant up-front investment and a great deal of patience and discipline. To successfully manage an SOA transition, it is best if your entire organization understands how the initial cost of attaining standardization within SOA will eventually lead to measurable enterprise-level improvements.

It all begins with the service. Ensuring that standards are applied right down to the interface level builds a foundation for a pure service-oriented environment with consistent endpoints that, in turn, fosters data sharing and highly composite solutions.

<definitions ...>
...
<message name="GetProfileNameRequest">
	<part name="ProfileID" type="xsd:int"/>
</message>
<message name="GetProfileNameResponse">
        <part name="ProfileName" type="xsd:string"/>
</message>
...
<operation name="GetProfileName">
     	<input message="tns:GetProfileNameRequest"/>
	<output message="tns:GetProfileNameResponse"/>
</operation>
...
</definitions>

<definitions ...>
...
<message name="GetProfileRequest">
	<part name="RequestValue" element="act:GetProfileRequestType"/>
</message>
<message name="GetProfileResponse">
        <part name="ResponseValue" element="act:GetProfileResponseType"/>
</message>
...
<operation name="GetProfileInfo">
     	<input message="tns:GetProfileRequest"/>
	<output message="tns:GetProfileResponse"/>
</operation>
...
</definitions>

<message name="GetProfileRequest">
	<part name="RequestValue" element="act:GetProfileRequestType"/>
</message>
<message name="GetProfileResponse">
        <part name="ResponseValue" element="act:GetProfileResponseType"/>
</message>

<message name="GetProfileRequest">
	<part name="RequestValue" element="act:Profile"/>
</message>
<message name="GetProfileResponse">
        <part name="ResponseValue" element="act:ProfileReport"/>
</message>
  

Send us your comments