Web Services Design Decisions

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?