SOA and how much information to disseminate

I was involved in a meeting today that made me think a little bit about how much detail is, and should be, shared when defining services and consumers.

To put this into context, there is Company A that has created application X (used by a number of different organisations) which needs to access common functionality from Company A, B and C. As Company A owns application X, as well as being one of the service providers, they are designing the service interface to be exposed by Company A, B and C.


Company A will create the Service Definition (preferably with input from all parties) as the primary owner of the system, but a burden of responsiblity has been placed on the other companies who will be implementing the service to provide details of their implementation in a supporting definition. This 'Consumer Definition' is intended to document the processes and flows that are followed in the implementation of the service interface, focusing on non-logical functionality such as error handling, logging, issue escalation and monitoring.

The two companies raised some concerns about this additional requirement, centered around two facts: Why should we provide this information; and as long as we conform to the interface why does it matter?

Both these concerns are valid, but I propose that providing such information is invaluable to good SOA architecture. While the service definition is the only thing that the services require, providing the additional information simply increases the ability for the users of the service to understand what is happening in each implementation. A contrived example would be if Company B's service is down, the administrators of the consuming application will know that an issue ticket should have been created in Company B's application fault log, and can contact Company B to verify the issue and obtain an ETA.

In a previous post I discussed some of the SOA points made by Steve Yegge from his time at Amazon, and this to me is clearly the sort of thing that provides massive value in SOA designs. In defining clear operational contexts for the services as well as the services themselves you can provide a much more meaningful and robust SOA environment.