Make Your Web Services “Easy Adopters”

This article is brought to you by Apress, publishers of Architecting Web

Services.

Web services are a new development paradigm with which you can expose logic

and data to partners and customers over the Internet. One reason so many people

are excited about Web services is that they can generate collaborations between

organizations with minimal communication. This is due mostly to the use of

human-readable XML for defining the data transfers during the consumption of the

Web service. Vendors are also starting to provide some of the first tools and

services that augment this fact by making the build and implementation of

rudimentary Web services quick and easy. However, as Web services and the

applications that consume them get more complex, you must still put a lot of

thought and attention into the design and deployment of your Web services to

ensure their success. Making your Web services “easy adopters” will give you a

competitive advantage over similar services.

The easier something is to use, the more people are likely to use it. There

is no better example of this basic premise than the Internet. While most

professionals cannot stand the hand-holding nature of AOL-type Internet service

providers (ISPs), there’s no disputing that they’re the biggest providers

because of their ease of use. You pop in a CD, run a program, and you’re

connected through a graphical, step-by-step process to the Internet. This same

approach also helps to keep these ISPs’ support costs down, because easier use

translates into fewer customer service issues. Of course, this experience must

be backed by the usual quality, or their conveniences and ease of use would be

pointless. If an ISP started to drop people off, have too many busy signals, or

incorrectly bill users, you can bet its user base would decrease

drastically.

You need to think of this same approach of easy adoption for your Web

services if you want to be successful. Two specific actions you can take today

to help make your Web services easy adopters are as follows:

• Design efficient interfaces
• Provide implementation assistance

Design Efficient Interfaces

If you take the approach that your Web services should be as easy as possible

to implement, you can start with the design of your interface. This is how

consumers will interact with your Web service, and if they can’t comprehend the

information going back and forth, they won’t get very far. XML plays a large

role in making your interface easy to use because it is easy to read. However,

you can still make the interface complicated despite this fact.

Let’s look at the example of a music catalog. You have a collection of

artists, albums, and songs that you want to expose through a Web service. If you

develop a search Web service to look up albums and songs, you could come up with

a combination of criteria for each, such as title, artist, year, and so on. This

could be built into separate routines with an albumSearch Web service and a

songSearch Web service. That would be two separate requests and responses, as

shown in the following table.

<albumSearch>
   <artist>Genesis</artist>
   <song>Heathaze</song>
</albumSearch>

<songSearch>
   <artist>Genesis</artist>
   <album>Duke</album>
   <track>6</track>
</songSearch>

<albumSearch>
    <album>Duke</album>
    <releaseDate>03-31-1980
    </releaseDate>
</albumSearch>

<songSearch>
    <song>Heathaze</song>
    <length>5:00</length>
</songSearch>

However, by being creative, you can also write a more generic Web service

called musicSearch. It could have the parameters of albumTitle, songTitle,

artist, and releaseDate. If a songTitle and artist were provided in the request,

the response would then be a list of albumTitle, artist(s), and releaseDate.

This could look like the documents in the following table.

<musicSearch>
    <songTitle>Heathaze</songTitle>     
    <artist>Genesis</artist>
</musicSearch>

<musicSearch>
    <albumTitle>Duke</albumTitle>
    <artist>Genesis</artist>
    <releaseDate>03-31-1980</releaseDate>
</musicSearch>

This approach makes for a much more usable interface where consumers can

specify all the information they know and the Web service fills in the holes.

This specific example is tied to the search of content, but you can take the

same approach to many Web services exposing different functionality. This

example is about an attitude and an approach to building a flexible, efficient

interface that will make your Web services easy to understand and implement.

Provide Implementation Assistance

The next step you can take toward making your service an easy adopter is to

provide implementation assistance. Especially with the paradigm being so young,

a lot of developers out there won't have all the training they need to work with

Web services. You can't afford to train each one, but there are things you can

do to help even experienced developers with the implementation of your Web

services. This assistance can encompass a wide range of value-added areas that

may make sense to implement for your consumers.

One such example of assistance is the designation of a test mode or

environment in which consumers can "play" with your Web services. This allows

consumers to work with your service in a safe manner so that they can understand

how it works and troubleshoot their implementation of it. This can be especially

helpful when providing a fee-based or transactional Web service, because it

could use test data and/or shorted functionality on the back end. The main

purpose of this test area is to allow developers to validate their requests,

handle valid responses, and test any authentication or security mechanisms in a

safe and unencumbered manner.

This test mode can range physically from an entirely separate service to a

parameter flag that allows requests to be treated as tests. Each has its

tradeoffs, with the separate service helping to offload the processing of dummy

requests and the test parameter flag making the process less complicated for

consumers to migrate from test to production. Your choice will depend upon your

policies and priorities.

Another area where you can provide implementation assistance is through

payload templates. If your Web service would likely involve human interaction

through the consumer, XML documents and/or XSL templates can be provided to help

with the collection of data or the formatting of responses. This doesn't take a

lot of effort on the provider's part, but it can help many consumers get up and

running with your Web service quickly. Even if consumers want to develop their

own presentation, these documents can act as samples or even foundations to help

them achieve their end result more quickly if they run into stumbling

blocks.

Summary

If you design efficient interfaces and provide implementation assistance,

consumers will be able to get up and running with your Web services fairly

quickly. This approach will become even more important when you start building

more sophisticated Web services involving workflows and newer security

mechanisms. Following through on making your Web service an easy adopter will

give you an advantage over your competitors. It takes a little more intelligence

on the Web service's part, but that's the way it should be in the Web services

paradigm.

This article is from Architecting Web Services by Apress To purchase the book, click on the title or the cover image. © Copyright Apress, All Rights Reserved

# # #