Tips for Web Services

I recently had the experience of writing a web service client to consume web services developed by another group. The process was considerably more painful than it needed to be, and the issues had nothing to do with the specific technologies involved.

I was tasked to develop a web service client in Java using the latest edition of JAX-WS (the Java API for XML Web Services) from Sun. JAX-WS is the successor to the JAX-RPC standard which has been used for Java applications previously. In support of JAX-WS, Sun has been working closely with Microsoft to enhance the interoperability between Java and .Net web services. This was key for me, because my Java clients were to consume several .Net web services.

While I worked on developing the client, I kept a list of both the good and bad things that I encountered when working with the web services. That initial list was the impetus for me to codify a set of tips on implementing web services effectively.

So, here are some tips to remember when developing web services:

  1. Web Services Are Building Blocks: If you're going to publish a web service, it needs to be ready for prime time. Web services aren't something you should just throw up in case somebody might want to use them. You're creating something that somebody else may very well use as a building block for another application.

    As such, your web service design needs to be solid from the start. That means that some serious design effort should go into determining what services will be offered, what arguments the web services will accept and what kind of response will be sent back to the client. This is especially important because the impact of design changes down the road can be high.

  2. Interface Consistency: When you're producing a set of web services, you're really producing an API for others to use. The API needs to be consistent. This extends to the names of the web services, argument names, argument types, etc.

    To give you an idea of how painful interface inconsistencies can be, here are some examples of real-life consistency problems that I have encountered:

    • My favorite is a web service called "EsclateEvent." Notice the typo in the name of the service. This looks unprofessional to users, regardless of how well the web service functions otherwise. In this case, "escalate" was spelled correctly in some places and wrong in others, which caused unecessary errors during the development process.

    • Inconsistent names and capitalization differences can also be problematic. For example, imagine that the web services interact with an enterprise tool like Netcool. Whenever the word is referenced in a service name, variable name, etc., it's inconsistent — sometimes appearing as "NetCool" or "Netcool". Another set of examples: "eventId" and "eventID".

    • Another gotcha is inconsistent types. Picture a set of web services that allow callers to perform tasks in response to certain events, such as sending emails about events, paging individuals, viewing the status of activities, etc. The problem was that some of the web services expected the event ID argument to be an integer, while others expected it to be a string. This proved painful if you were the developer tasked to produce a web client to consume some of the services, because you could never be sure what type an argument was supposed to be without double-checking against the WSDL file.

  3. License: Once you've produced a web service, somebody in management will invariably ask you who's using your web service. A web service used by numerous applications or organizations will generally be deemed more successful by management than one with fewer users.

    Developers will also want to know who is using their web services in case significant changes are ever needed. You can't evaluate the effect of changes unless you can understand the impact of the changes on your userbase. And if you don't know who your users are, well, you're out of luck.

    The usual solution for identifying the users of a web service is to have a license key that must be provided as an argument in order to use a web service. Supporting a license key generally requires the following things:

    • The web services will accept a license key as an argument (usually the first argument). If an invalid license key is provided, the web service will simply return an appropriate error message.

    • You'll probably need a separate web application to manage license keys. Specifically, you'll want to have a way for users to submit a request for a license key, and you'll want to make sure that the request form solicits sufficent information about the individual, organization and application(s) that will be using the service. The application will also need the capability to generate license keys, store the keys and related information in a database and provide simple administrative features for managing the license keys.

  4. Usage Metrics: The next question most asked by management with regard to web services is: How heavily is the service being used? This information is often used as a justification for the cost of developing the web services, so it's a good thing to have.

    It's useful to add some sort of logging or tracking capability to web services so that usage statistics can be easily generated. If a license key is used, then the metrics can go one step further and even provide statistics about usage by organizations or applications.

  5. Feedback: Web services should provide useful feedback to the caller. At a minimum well-defined error messages can assist assist developers in debugging problems.

    Going beyond that, web services are often leveraged by other applications. Accordingly, a web service should provide feedback to the caller concerning any operation performed.

    For example, if the web service sends an email or a page, it's useful to inform the caller whether the email or page was successfully sent. If the service stores a new record in the database, thereby generating a unique primary key for the record, it could be beneficial to inform the caller that A) the record was successfully created, and B) it was stored with a primary key value of 123.

    The goal, of course, is to ensure that a web service can function as the best possible building block for other applications.

So, these are some tips for producing better web services, based on some hard experience in the real world. I hope these tips prove useful to others.


David Keener By dkeener on Friday, August 27, 2010 at 12:20 AM EST

This article was written in response to a poorly design SOAP web service that I had to work with at one point. Most of the points that I made are also relevant for RESTful web services, as well.

Leave a Comment

Comments are moderated and will not appear on the site until reviewed.

(not displayed)