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.
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.
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?
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.