Well defined interfaces

On an SOA mailing list I follow, someone recently posted a very simple question. What is a well-defined interface? The notion of a well-defined interface is frequently cited as a requirement for a good service, but the discussion usually heads in the technology direction of WSDL, IDL, WS-Policy, etc. In terms of importance to an enterprise SOA, I think that the use of standard description techniques is far less important than the qualitative aspects of being well-defined. As I see it, a well-defined interface is one where the actions that will be performed by the service provider are clear and unambiguous. Does using WSDL and WS-Policy ensure this? Absolutely not. Just as the use of standard look and feel guidelines and common user interface toolkits do not guarantee a highly-usable user interface, the use of WSDL and WS-Policy do not guarantee a highly-usable service interface. After all, the reason for defining something well is so that others will use it.

Defining an interface so that the behavior is clear and unambiguous is a very difficult thing to do. Rooted in binary technology, typical IT systems are not designed to deal with ambiguity. Where ambiguity exists, we design systems take a decision tree based approach, always dealing with yes/no decisions. Systems break down when they enter an unexpected state, a situation not modeled in the decision tree. When this decision logic is represented in source code, the cost to go in and add new logic to handle the unexpected state is high.

A very simple example that is timely for those of us in the USA is tax filing. Those of us who do our own taxes often use a system like TurboTax or TaxCut. The final step in the process is the electronic filing of a return. Let’s suppose I am providing an tax return filing service. There are state and federal fees to be collected. How should these fees be represented in the service interface? Hypothetically, the fee could be paid by extracting the fee from any refund the filer is due, they could supply a credit card, it could be electronically deducted from a bank account, a payment service like PayPal could be utilized, or a filer from previous years may have a payment preference on file. What happens if the credit card is rejected? What happens if the tax return is rejected?

When working with human-to-system interactions, systems can deal with this ambiguity by having a very generic return type, such as an HTML page. The interpretation of the response is left up to the human, and we’re good at processing ambiguities. This doesn’t work for system-to-system interaction. The analogous approach would be a web service that returns a message that can be any well-formed XML document.

Choreography is a big part of this. While we may try to decompose things to simple request-response patterns, the real world doesn’t work that way. What may have looked like a simple placeOrder operation may need to be modeled as a conversation, with only one path being a simple request-response. When conversations are involved, we now have to deal with system behavior when one party stops communicating. If I’m a cashier, and I tell a customer that they need to give me more money, I can infer that when they walk away from the counter without giving me the additional money, they’re not going to buy the product any more. I don’t sit there waiting for a response from them, and require the store manager to find another cashier to wait on customers. So what’s my advice? There are two things.

First, we still need to strive to take as much ambiguity out of the system-to-system interaction as possible. Systems must have some level of agreement on the semantics of the interchange and the policies associated with the interchange, including the semantics of the policies (we need domain specific policy languages). That being said, the ambiguity will never go away. If we only focus on removing ambiguity, we’re doing ourselves an injustice. I would argue that removing ambiguity results in more rigid systems, which is exactly the opposite of where we want to be. We’re adopting SOA to allow for increased flexibility and agility, not increased rigidity.

While embracing standards, we must also know that change will continue to occur and ambiguous situations will continue to arise. As a result, the second thing must be a focus on efficient management and incorporation of that change. While SOA and Web Services allow us to remove ambiguity, the worlds of BPM and EDA allow us to efficiently address ambiguous situations and changes to the interaction model. BPM and BAM technologies are allowing the interaction to be modeled and executed by run-time engines, including the ability to run simulations based upon new process variations and new interactions. Event processing allows analysis of a flowing stream of events to infer state (the key to recognizing an ambiguous situation), that can now drive new decisions in the process or new service invocations. Brenda Michelson has a great blog entry that goes into this in more detail, with some feedback from Joe McKendrick at ZDNet. For more on the well defined interface, check out Miko Matsumura’s comments on the same thread and pizza shop blueprint as well.

6 Responses to “Well defined interfaces”

  • miko:

    Well dang!

    Dont they say “great minds think alike”???

    Are you going to WS on Wall Street? Lets hang out there! Send me an email!

  • Todd- Great points…

    For services to be consumed, their ‘job’ must be well understood.

    Your warning on avoiding ‘rigidity’ by combining SOA with EDA and BPM, (also business rules processing) is important for SOA practitioners to understand.


  • Hi Todd,

    Have you looked at WS-CDL? I’ve had good conversations with Steve Ross-Talbot about use cases like the cash register one using CDL…


  • Administrator:


    Based on some of Steve’s comments on the mailing list, I’ve just begun to look into WS-CDL. This was actually one of the first examples I came up with on my own where the importance of choreography was crystal clear. Slowly, it will make it to the top of my pile of things to read…

  • WaltDe:

    Very good reading. Peace until next time.

  • […] Well defined interfaces: This post is the oldest one on the list, from February 24, 2006. It discusses what I believe is the important factor in creating a well-defined interface. […]

Leave a Reply


This blog represents my own personal views, and not those of my employer or any third party. Any use of the material in articles, whitepapers, blogs, etc. must be attributed to me alone without any reference to my employer. Use of my employers name is NOT authorized.