The Ancient Art of Programming

The most central concept within a Web Service is its Contract. In this contract, you define:

• the name, and other properties of the service,
• the operations it supports, and
• the messages accepted and sent by the operations.

Together with the Binding of the service, this makes a Endpoint, i.e. something you can point a client at.

For SOAP services, the contract is defined in a WSDL definition. It usually contains, or refers to, a XSD schema that defines the messages of the operations.

The most common way to create a WSDL document is to generate it by the SOAP stack. The Alpine people call this contract-last development, and also mention a few issues with it. In my opinion, the most important issue is that:

There is no way to ensure that a service’s published interface remains constant over time. Every redeployment of the service may change the classes, and hence the contract.

The alternative of contract-last development is, of course, contract-first development. Using this approach, you start with the WSDL and schema, and create server-side stubs afterwards, if necessary. Because of the complexity of WSDL, and especially XSD schemas, this approach is not often used, but I think that using contract-first service development should be considered a best practice.

Luckily, this approach is practiced by some. Especially in large corporations, where multiple development teams work together to implement a service, or where one team defines the service while others use it as a client, the contract-first approach is used often. As one of my customers put it: it is not an option to regenerate client stubs every day or so. I totally agree; would you accept monthly changes in a legal, real-life contract? Why should your service contract be any different?