Over a million developers have joined DZone.

Making a Service Catalog Work: 3 Do’s and Don'ts

DZone's Guide to

Making a Service Catalog Work: 3 Do’s and Don'ts

· Integration Zone ·
Free Resource

WSO2 is the only open source vendor to be named a leader in The Forrester Wave™: API Management Solutions, Q4 2018 Report. Download the report now or try out our product for free.

A couple of years ago many organizations were taking their first steps into the world of SOA. Their main concern was which ESB to choose. After deciding whether to use the ESB from Tibco, Cordys, IBM, Oracle, or Microsoft, they thought the hard part was over. They started building web service like crazy and ended up with JABOWS (Just A Bunch Of Web Services) instead of a decent SOA. At the moment, I’m getting a lot of questions from clients regarding service identification and service specification (and SOA governance, but this will be topic of another blog post). Service identification is the process of determining which services the organizations actually needs. A while ago two colleagues and I wrote an article about ten frequently used approaches (http://www.soamag.com/I13/1207-1.asp). You’re welcome to comment if you see any approaches we did not describe. Of course, an organization cannot implement all the candidate services at the same time, nor does it need to. It starts out with the services having the highest priority and gradually builds its service portfolio. Now, as the portfolio grows, it is hard to keep track of the functionality of all these services. The service catalog becomes an important artifact for the service consumers to discover services and determine whether or not they fit their requirements. Even if you don’t ‘believe’ in the concept of reuse: consumers need a precise and unambiguous service specification to be able to use the service. If provider and consumer have different expectations of the behavior of a service, you’re bound to get problems. Let’s have a look at three do’s and don’ts for the service catalog.


1) Appoint a service catalog manager 

Though the service provider is responsible for specifying his service, we also need a service catalog manager. This person checks whether the quality of the service specifications meets the standards. He keeps the catalog up and running. And, most importantly, he leads the processes of accepting a new service, changing the life cycle status of a service, versioning services, and killing services. No chance for JABOWS with a service catalog manager around! 

2) Make a canonical data model

It is important for services to speak the same language. Usually the ESB is used for mapping data from a native application format to the canonical data model. The canonical data model differs from the so-called corporate data model. The corporate data model describes all data within the enterprise. The canonical data model only describes data to be exchanged by services. Do not only pay attention to specifying the syntax of the data, but also to the semantics. We would not want another space shuttle to crash because of a simple inch/centimeters mix-up. 

3) Specify who, what, and how

Essentially thee aspects are important in a service specification: the who, what, and how. We want to know who offers the service; do we trust this person and how can we contact him if needed? We want to know what the service does, e.g. input, output, preconditions, postconditions, description of behavior. Also, the non-functional behavior (e.g. availability, security etc) belongs to this `what’ part. Finally, we are interested in how we can access the service. We need to know the location of a service (usually a logical location) and what protocols to use. Sometimes we are also interested in `how much’, i.e. what do we need to pay to use the service.


1) Assume WSDL is enough

Don’t think the WSDL is enough for the consumer of the service to know what the service does. It just isn’t. Additionally, the WSDL is only suitable for one type of stakeholder: the software engineer.  

2) Assume the UDDI standard is enough 

The UDDI standard work fine for dealing with a number of technical aspects and it gives information about who offers the service and how to access the service. However, it lacks proper means to describe the `what’ part. Most organizations use commercial service registries with add-ons on the UDDI standards, or additional Word or Excel templates. 

3) Assume providers will fill the catalog if they are not rewarded

Building as well as specifying services takes time, money, and effort. It is important to realize that service providers will only make services for service consumers if they are somehow rewarded. Both parties should have costs and benefits. A provider will not cooperate if there are only costs involved for him.

IAM is now more than a security project. It’s an enabler for an integration agile enterprise. If you’re currently evaluating an identity solution or exploring IAM, join this webinar.


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}