What are the pros and cons of each approach, and which approach would you prefer

Contract-first Web service

PROS:

  • Clients are decoupled from the server, hence the implementation logic can be revised on the server without affecting the clients.
  • Developers can work simultaneously on client and server side based on the contract both agreed on.
  • You have full control over how the request and response messages are constructed — for example, should “status” go as an element or as an attribute? The contract clearly defines it. You can change OXM (i.e. Object to XML Mapping) libraries without having to worry if the “status” would be generated as “attribute” instead of an element. Potentially, even Web service frameworks and tool kits can be changed as well from say Apache Axis to Apache CXF, etc.

CONS:

  • More upfront work is involved in setting up the XSDs and WSDLs. There are tools like XML Spy, Oxygen XML, etc to make things easier. The object models need to be written as well.
  • Developers need to learn XSDs and WSDLs in addition to just knowing Java.

Contract-last Web service

PROS:

  • Developers don’t have to learn anything related to XSDs, WSDLs, and SOAP. The services are created quickly by exposing the existing service logic with frameworks/tool sets. For example, via IDE based wizards, etc.
  • The learning curve and development time can be smaller compared to the Contract-first Web service.

CONS:

  • The development time can be shorter to initially develop it, but what about the on going maintenance and extension time if the contract changes or new elements need to be added? In this approach, since the clients and servers are more tightly coupled, the future changes may break the client contract and affect all clients or require the services to be properly versioned and managed.
  • In this approach, The XML payloads cannot be controlled. This means changing your OXM libraries could cause something that used to be an element to become an attribute with the change of the OXM.