Michael Gilfix Online

Using proper Web Service interface design can greatly improve application responsiveness and simplify integration logic. Poor design will not only bog down logic, but actually increase the complexity of both client and server-side implementation by requiring both to handle a larger number of possible error cases. This post attempts to capture three key patterns for designing/improving Web Service interfaces. While this article approaches the problem from the perspective of Web Services, many of these principles apply to Web Service design.

Appropriate Granularity:

The traditional interface design paradigms that folks are used to using in OOP and functional languages are often inappropriate for remote interfaces. They favor having many different methods that can be used to query information or state about an objects internals. This is particularly true for data objects. Since each query results in a remote interface invocation, querying information can quickly add up. A better approach is to use the Data Transfer Object (DTO) pattern that is heavily talked about in the concept of remote EJBs. The DTO is a data object that contains all queriable information in a single data object, which is transferred once. The cost of transferring more data in a single shot is marginal compared to the latency cost of going back and forth. This is particularly true for interfaces that allow you to create/update/query/delete data objects.

When people typically think of Web Services, they think of remote calls that cross system boundaries and typically networks. Web Services is also typically used with the design philosophy of Service-Oriented Architecture (SOA), which suggests encapsulating a bunch of business logic and function as a callable service with a more granular interface. A huge advantage of Web Services is how is supports a loosely coupled componentization model. This can be a boon for developing flexible, scalable systems that support dynamic selection of function at runtime; Web Services can effectively be used to bind together internal components of the system as well as exposing more granular services. This technique of binding together the system also supports a very flexible packaging model. In J2EE parlance, components can be bundled as multiple WAR files in a single EAR or as a set of EARs, where each EAR contains a single and very self-contained component.

The usual concern with this approach of moving one step down in granularity from the service level is one of performance: in the CPU cost and latency of making the Web Service invocation. This is where local Web Services optimization comes in. Within a cluster of application servers, all components can be distributed to each application server; each application server contains a copy and executes all the code for each components. In this example, each component is packaged in its own EAR -this comes with advantages discussed below. When calling shared components, the fronting service or component is configured with a local endpoint is given to the Web Service runtime: http://localhost/foo/endpoint. Each copy of the service code makes an invocation with the localhost endpoint, thereby hitting local code.