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.
- Attaching policies and SLAs. As Vambenepe explains:
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.