SOAP Web Services Approach
This tutorial will discuss different approaches to development of the SOAP Web Services (WS). Both approaches use SOAP over HTTP protocols and define endpoints and operations via a Web Services Definition Language (WSDL) file. The two approaches are contract-first and contract-last. Even though the technology stack can be similar for both methods, they differ in both the methodology and the implementations.
What is Service Contract?
A service contract is comprised of one or more published documents (called service description documents) that express meta information about a service. The fundamental part of a service contract consists of the service description documents that express its technical interface. These form the technical service contract which essentially establishes an API into the functionality offered by the service.
Contract First Approach
With Contract First approach for web services development, you start off with defining the XML Schema/WSDL contract for your service instead of Java code. One you have defined a WS- Compatible WSDL, you can take any programming language like Java or .Net for its implementation.
Contract Last Approach
Contract-last is the other way around you design how your service is going to work, then make one or more methods available as the interface for other services. The problem with contract last is that there is a tight coupling between your code and the WSDLs you produce. It means that you are limited by the impedance mismatch between Java and what an XSD supports. The major issue we've faced is around versioning. If you want to support two parallel versions, how do you do that with contract-last? We found a cunning way to do it with XStream and separate wars but the solution is too large for this margin.
Difference between Contract First and Contract Last Approach
In the contract-first web service, the "contract" (a WSDL definition of operations and endpoints and XML schema of the messages) is created first, without actually writing any
service code. In the contract-last web service, existing logic is "exposed" as a web service and the contract is created at the very end.
Contract-last takes an existing Java interface and from that, creates your web service. On reflection, you'd think that this meant create a schema contract, but generally it seems to mean getting hold of some tool that will take a Java interface as an input and deliver a WSDL as an output.
Research seems to show that, at the time of writing, contract-first is preferred over contract-last and various reasons are given:
- Object to XML impedance mismatch, which generally means that with contract-last, some Java types don't readily convert to XML and if they did then there could be a certain loss of information as defined by an XSD's <restriction> element. I.e, Java isn't really expressive enough to produce a rugged contract.
- Contract-last could suffer from performance issues as you, the developer, have no control of what's sent over the wire.
- Using contract-first means that you have your XML types defined in a set of separate schema files, which could be re-used effectively.
- Contract-first has looser coupling between definition and implementation making version management easier
- One of the positive things about web services is that they allow services written in different languages to work together. Contract-first reinforces this approach as the WDSL/XML Schema provides a programming language independent, centralised method of specifying a contract. Contract-last, on the other hand, means that your contract is defined in your implementation code, which may differ from your client's implementation code and who's to say which is the master copy of the code?
- Which brings us on the next benefit of using contract-first: the management of change. There is usually a version 2 of an interface adding in something that was forgotten in version 1. Using a schema makes that change management easier.
- Finally, a plus point for contract-last is that it should be easier, there's no messing about with XSDs, meaning there are no extra skills for your team to learn.