Do We Really Need Service Descriptions?

| by Boris Lublinsky on Oct 20, 2010. Estimated reading time: 3 minutes |


It is a popular opinion that one of the main complexities of SOAP-based Web Services is usage of Web Services Description Language (WSDL) for describing service interfaces. Another problem with WSDL described by William Vambenepe is that WSDL and stub generation tools built with it create distributed applications which are too tightly coupled. As people started to realize these issues, instead of improving service definition

... they threw out the whole idea of a service description. And now, in the age of APIs, we are no more advanced than we were 15 years ago in terms of documenting application contracts. It’s tragic.

In his post Vambenepe discusses two important fallacies that are typically used to justify such decision:

  • There is NOT One True Description for a given service. According to Vambenepe:
    It’s perfectly fine to have service descriptions that are optimized to meet a specific need rather than automatically focusing on syntax validation. Not all consumers of a service contract need to be using the same description. It’s ok to have different service descriptions for different users and/or purposes.

    Although in his post Vambenepe is talking mostly about different formats for a given service, his statement has a significantly wider reach. As technicians, for a long period of time, we have been focusing only on service description for developers (API definitions), ignoring the needs of business analysts - people that have to make decisions about the applicability of a service for a specific enterprise solution. They typically need information about the service that goes way beyond "traditional" API definitions (service description), for example:

    • What business functionality does the service provide?
    • What are the limitations of the service?
    • Which SLAs does the service support?
    • What are requirements that the service requester must satisfy to invoke the service successfully?
    • What are the conditions under which particular service execution outcomes will occur?
  • A service description does NOT mean you have to validate messages. As noted by Vambenepe:
    There are many other ways in which service descriptions could be useful, but they have been largely neglected because of the focus on syntactic validation and stub generation.

    Some of the use cases for service description listed in the post include:

    • Attaching policies and SLAs. As Vambenepe explains:
      One of the things that WSDLs are often used for... is to attach policies and SLAs. For that purpose, you really don’t need the XSD message definition... You really just need a way to identify operations on which to attach policies and SLAs. We could use a much simpler description language than WSDL for this. But if you throw away the very notion of a description language, you’ve thrown away the baby (a classification of the requests processed by the service) along with the bathwater (a syntax validation mechanism).
    • Governance / versioning. The ability to discover when service definition change:
      One benefit of having a service description document is that you can see when it changes. Even if you reduce this to a simple binary value (did it change since I last checked, y/n) there’s value in this. Even better if you can introspect the description document to see which requests are affected by the change. And whether the change is backward-compatible.

A formal service description is definitely important and the drawbacks of WSDL should not be the grounds for its complete dismissal. It would be nice if the next version of service description would go beyond what WSDL or Web Application Description Language (WADL) are today - "machine-readable" description of services. A service is significantly more than just an API - it is a building block for creating solutions. As a result, a service description should be more than just an API definition, but something that can satisfy all of the stakeholders participating in the service’s lifecycle.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

interesting by Steve Snodgrass

Nice post. Thank you. I can't say I'm a fan of WSDL but I do think it serves a purpose and I use it extensively. I am curious as to how "WSDL and stub generation tools built with it create distributed applications which are too tightly coupled". I read the article you reference and didn't find an explanation there. Could you please briefly explain the thinking behind this statement?

Re: interesting by James Kao

William doesn't explicitly say the phrase "tightly coupled" in his posting, but the implication is that WSDL (and really the use of XSD) creates bindings that are hard to change. This is really an artifact caused by the most convenient way to consume WSDL: feeding them to a stub generator. Since the stub is auto-generated code, suddenly all the clients become extremely sensitive to changes to the XML definition, even backwards-compatible ones, like adding an optional field.

Re: interesting by Steve Snodgrass

Thank you for the reply James. WSDL -> XSD -> "auto-generated stubs" -> "inflexible code" -> "tightly coupled systems". That's downright crazy logic.

service descriptions by Matthew Rawlings

Any real world service landscape has more than 2 Participants. WSDL, just like an API has only caller and called / provider and consumer.

For a n-way API / Service Definition you should try Scribble from Red Hat. Handles hundreds of Participants just fine.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

4 Discuss