Service catalog

Javadoc for services

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?

About the author

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.

You can find Simon on Twitter at @simonbrown ... see for information about his speaking schedule, videos from past conferences and software architecture training.

Re: Service catalog

I am waiting for the day when the web 2.0 tagging tools get used to document and describe all kinds of project artifacts. I would like to see a service tagged by its users to describe what it does, or what it uses, or both.

Re: Service catalog

You can document services to the n-th degree and still miss opportunities for reuse. Indeed, the more you document, the more you present a specialised interface and the more reticent a team will be to adopt the service. The service should have been implemented with the minimal functionality for its intended purpose and will never grow unless it advertises what else it could do within its original remit.

Thus I'd argue that service documentation needs to reach beyond the existing interface. I would opt for breadth in the documentation - with a means of contacting the team responsible for the service. They should know what's possible and (hopefully!) be able to provide appropriately detailed documentation for their service's interface.

Re: Service catalog

I like the idea of a service telling others what it could do. Do you have any specific examples in mind? Do you see this being applicable to both business and technical services?

Re: Service catalog

You could be looking for IBM's Service Registry, which is namechecked over here and here.

Re: Service catalog

I might be, but I don't seem to be able to find much more than the namecheck! ;-)

Re: Service catalog

Patience, young grasshopper ;-)

Re: Service catalog

Hi! I've got a repository of services that are defined and catalogued and serve as a service router. It stores endpoints config settings and acts as a notification service as well..

Re: Service catalog

Hi, I am involved in building service catalogue and I am looking for template to start with. Could any of you please share this with me please?

Re: Service catalog. SOA-like services vs. IT Business Services

Hi all, I am working as a consultant defining IT Service Catalogues for big companies, from the point of view of Business services provided by the IT organization. The proposed information to capture in the SOA service catalogue is in some sense similar as the IT Business Service definition. There are other attributes for an IT Business Service, like value to the business and conditions to use the service from the user perspective, cost information, etc. Nevertheless, I did not find in my usual sources a good definition of a model with the relationship between SOA-like services and Business services delivered by an IT organization. Does anyone worked on this topic or do you have information about?

Add a comment Send a TrackBack