Having been involved in an SOA project, one of the lessons that I've learnt is that we need to be far smarter in the way that we manage, organise and reuse services. One of the key promises of SOA is reuse on a much more granular level than one could ever hope to achieve with pure object oriented techniques, but my experience suggests that reuse isn't something that you get for free. Particularly, reuse problems arise when others within your team|department|enterprise don't realise that you've already defined and/or built a particular service that they could reuse. How do you solve this? Well I think that the answer to this is two-fold.

1. Define : ensure your service interfaces are agreed upon up-front.
2. Catalog : document the basics of each service somewhere.

The first part (service definition) won't come as any surprise, but it's a prerequisite for the second part, which is all about building a service catalog. One of the hardest parts of SOA is actually defining the services in the first place and, once this is done, cataloguing them is fairly straightforward. However, without this last step, how do you easily work out what services are available to you and the operations they provide.

First of all, what sort of information is it useful to capture in a service catalog? My initial suggestion would be as follows.

• Service name
• Description
• Type of service (e.g. business, application specific, data, etc)
• Service level agreements and other quality of service characteristics (e.g. performance, scalability, security, availability, etc)
• For each service operation
  • Operation name
  • Description
  • Request/response messages | input/output parameters and possible errors
  • Pre-conditions
  • Post-conditions
  • Whether the operation is idempotent

So what alternatives do we have for building a service catalog? In the case of web services, one option is to augment the WSDL used to define the services, perhaps performing an XSLT transformation on the document to make it more readable, perhaps in a HTML format. This might work if you have control over the generation of your WSDL, but many tools auto-generate it for you. Another option is to build your service catalog within a UML model. This is the approach that I've seen tried and while it's easy to define services, their operations and the common view of data that those operations work upon, some of the other aspects are harder to document. Well, they're not harder to document because most modeling tools support the notion of adding your own metadata to your classes. It's finding the information that is hard. Ideally it should be be readily available and people shouldn't have to click through lots of dialogs to find this "hidden" metadata. Unless you can get some good reports out of your modeling tool of choice, I'd be tempted not to use it for this purpose.

Ultimately, I think a simple text/HTML file or Word document is the best option because it's more easily accessible to all types of users, including those on the business and technical sides. Of course, this doesn't mean that you need to manually create it. If you can automatically extract information from your UML model|WSDL|annotations in Java implementations|etc then you'll spend less effort keeping the catalog up to date.

What do you think? If you've used something like a service catalog, what information did it capture and how?

Responses[9]

Posted by Simon Brown on 27 March 2006 20:02:01 BST #