Key Web Services Design Decisions

Key Web Services Design Decisions

Now that you understand what happens in a Web service interaction, let us look further at the issues involved in the design and implementation of a Web service. We first look at what goes into designing a Web service, examining the issues for which decisions are required and, when possible, making recommendations. (Similarly, Chapter 5 examines the issues to consider when designing a Web service client.) Before doing so, it is worthwhile to repeat this point:

graphics/box_icon.gif Web service technologies basically help you expose an interoperable interface for a new or an existing application. That is, you can add a Web service interface to an existing application to make it interoperable with other applications, or you can develop a completely new application that is interoperable from its inception.

It is important to keep in mind that designing Web service capabilities for an application is separate from designing the business logic of the application. In fact, you design the business logic of an application without regard to whether the application has a Web service interface. To put it another way, the application's business logic design is the same regardless of whether or not the application has a Web service interface. When you design a Web service interface for an application, you must consider those issues that pertain specifically to interoperability and Web services—and not to the business logic—and you make your design decisions based on these issues.

When designing a Web service, consider the logic flow for typical Web services and the issues they address. In general, a Web service:

  • Exposes an interface that clients use to make requests to the service

  • Makes a service available to partners and interested clients by publishing the service details

  • Receives requests from clients

  • Delegates received requests to appropriate business logic and processes the requests

  • Formulates and sends a response for the request

Given this flow of logic, the following are the typical steps for designing a Web service.

  1. Decide on the interface for clients. Decide whether and how to publish this interface.

    You as the Web service developer start the design process by deciding on the interface your service makes public to clients. The interface should reflect the type and nature of the calls that clients will make to use the service. You should consider the type of endpoints you want to use—EJB service endpoints or JAX-RPC service endpoints—and when to use them. You must also decide whether you are going to use SOAP handlers. Last, but not least, since one reason for adding a Web service interface is to achieve interoperability, you must ensure that your design decisions do not affect the interoperability of the service as a whole.

    Next, you decide whether you want to publish the service interface, and, if so, how to publish it. Publishing a service makes it available to clients. You can restrict the service's availability to clients you have personally notified about the service, or you can make your service completely public and register it with a public registry. Note that it is not mandatory for you to publish details of your service, especially when you design your service for trusted partners and do not want to let others know about your service. Keep in mind, too, that restricting service details to trusted partners does not by itself automatically ensure security. Effectively, you are making known the details about your service and its access only to partners rather than the general public.

  2. Determine how to receive and preprocess requests.

    Once you've decided on the interface and, if needed, how to make it available, you are ready to consider how to receive requests from clients. You need to design your service to not only receive a call that a client has made, but also to do any necessary preprocessing to the request—such as translating the request content to an internal format—before applying the service's business logic.

  3. Determine how to delegate the request to business logic.

    Once a request has been received and preprocessed, then you are ready to delegate it to the service's business logic.

  4. Decide how to process the request.

    Next, the service processes a request. If the service offers a Web service interface to existing business logic, then the work for this step may simply be to determine how the existing business logic interfaces can be used to handle the Web service's requests.

  5. Determine how to formulate and send the response.

    Last, you must design how the service formulates and sends a response back to the client. It's best to keep these operations logically together. There are other considerations to be taken into account before sending the response to the client.

  6. Determine how to report problems.

    Since Web services are not immune from errors, you must decide how to throw or otherwise handle exceptions or errors that occur. You need to address such issues as whether to throw service-specific exceptions or whether to let the underlying system throw system-specific exceptions. You must also formulate a plan for recovering from exceptions in those situations that require recovery.

After considering these steps, start designing your Web service by devising suitable answers to these questions:

  • How will clients make use of your services? Consider what sort of calls clients may make and what might be the parameters of those calls.

  • How will your Web service receive client requests? Consider what kind of endpoints you are going to use for your Web service.

  • What kind of common preprocessing, such as transformations, translations, and logging, needs to be done?

  • How will the request be delegated to business logic?

  • How will the response be formed and sent back?

  • What kinds of exceptions will the service throw back to the clients, and when will this happen?

  • How are you going to let clients know about your Web service? Are you going to publish your service in public registries, in private registries, or some way other than registries?

Before exploring the details of these design issues, let's look at a service from a high level. Essentially, a service implementation can be seen as having two layers: an interaction and a processing layer. (See Figure.)

graphics/box_icon.gif It is helpful to view a service in terms of layers: an interaction layer and a processing layer.

2. Layered View of a Web Service


The service interaction layer consists of the endpoint interface that the service exposes to clients and through which it receives client requests. The interaction layer also includes the logic for how the service delegates the requests to business logic and formulates responses. When it receives requests from clients, the interaction layer performs any required preprocessing before delegating requests to the business logic. When the business logic processing completes, the interaction layer sends back the response to the client. The interaction layer may have additional responsibilities for those scenarios where the service expects to receive XML documents from clients but the business logic deals with objects. In these cases, you map the XML documents to equivalent object representations in the interaction layer before delegating the request to the business logic.

The service processing layer holds all business logic used to process client requests. It is also responsible for integrating with EISs and other Web services. In the case of existing applications adding a Web service interface, the existing application itself typically forms the service processing layer.

Viewing your service implementation in terms of layers helps to:

  • Clearly divide responsibilities

  • Provide a common or single location for request processing (both pre- and post-processing) logic in the interaction layer

  • Expose existing business logic as a Web service

To put this notion of a layered view in the proper context, let's look at an example such as adventure builder's business process Web service scenario. In this scenario, a partner travel agency uses adventure builder enterprise's Web service to build a travel itinerary for its clients. Through the service interface it exposes to these travel agencies, adventure builder enterprise receives business documents (in XML format) containing all required details for travel itinerary requests. Adventure builder uses its existing workflow systems to process and satisfy these partner requests. The interaction layer of adventure builder's exposed Web service interface validates these incoming business documents, then converts the incoming XML documents to its internal format or maps document content to Java objects. Once the conversion is finished, control passes to the workflow mechanisms in the processing layer where travel requests are completed. The interaction layer generates responses for completed travel requests, converts responses to XML documents or other appropriate formats, and ensures that responses are relayed to the partner agencies.

It is important to clarify the extent of the preprocessing performed at the interaction layer, since it differs from the JAX-RPC runtime processing. Adventure builder's interaction layer—its exposed Web service interface—applies service-specific preprocessing to requests coming in to the service. This service-specific preprocessing is performed only if required by the service logic, and it includes converting incoming XML documents to a suitable form or mapping the document contents to Java objects. This mapping of incoming XML documents to business objects is not the same as the JAX-RPC runtime mapping between XML documents and Java objects. Although the container performs the JAX-RPC runtime mapping for all requests and responses, the developer chooses the mapping of incoming XML documents to business objects.

graphics/box_icon.gif Although there are advantages, as noted previously, to viewing a service in terms of interaction and processing layers, a Web service may opt to merge these two layers into a single layer. There are times when multiple layers make a service unnecessarily complicated and, in these cases, it may be simpler to design the service as one layer. Typically, this happens in scenarios where the logic in either layer is too small to merit a separate layer.

The weather service scenario is one such service that might benefit from merging the interaction and processing layers into a single layer. This type of service does not need to preprocess incoming requests. A client request to the service for weather information simply includes a name or zip code to identify the location. The service looks up the location's weather information, forms a response containing the information, and returns it to the client. Since incoming requests require no preprocessing, a layered view of the weather service only complicates what otherwise should be a simple service.

     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows