Contract-First Design
- Dimuthu Leelarathne
- Architect - WSO2
Many developers may still prefer a code-first approach to service creation, due to a perception that it is faster. But contract-first design has other benefits that should be considered carefully. In this article, Dimuthu Leelarathne provides an overview of the advantages of a contract-first approach.
Table of Contents
Contract-first Design
In a contract-first approach, you start development by defining the contract, or the 'interface' of the service. In the code-first approach you start development from code and then create the contract. Software that is designed using interfaces hides implementation details and promotes code reuse. In the same way, carefully designed contract-first design services lasts years with minimal changes, which saves time, effort and money.
There are two main arguments against contract-first design: the time and effort from multiple parties to collaborate and agree on a contract, and the complexity of WSDL and XML schemas. A truly contract-first design can be less productive in the initial design phase.
If services are created from code that was not designed to exposed as services, it will have adverse impacts. The service may be tightly bound to the program language constructs hindering interoperability and portability. The service operations will be either too fine grained or coarse grained. If the service interface has fine-grained operations, there will too many SOAP messages going back and forth. Furthermore, there can be several interdependent operations that are not atomic in nature. Above all, if the service does not desired results to all involving parties then it must undergo change. In the contract design methods these can be eliminated easily.
Contract-first design advantages
- Loose coupling between applications
- Interoperability between multiple services
- Collaboration and agreement between all parties, hence the service undergoes none or minimal changes during it's lifetime
- Abstraction hides underlying implementation details
SOA is defined as the "Interoperability of collection of distributed, loosely coupled heterogeneous services; to orchestrate a series of business tasks, to achieve a specific business process objective."[1] Service contract is one of the main feature of SOA and some experts even include it in the definition of SOA. The contract loosely couples the relationship between the service provider and the consumer. It is clear that contract-first approach is in line with the definition of SOA. So, to make the most out of SOA with contract-first approach is the way to go.
If the service is a short-lived, ad hoc service where productivity is the main concern, then the code-first approach may be appropriate. Otherwise, if the service is to be long-lived among the enterprise, and intended to be reused, then it is better to adopt a contract-first approach.
Designing a Contract
When designing a service, using contract-first design does not guarantee a good contract. Success of a contract depend on collaboration to identify the elements that should be represented in the service. If possible, all parties interacting with the service should take part in the contract defining stage. A good service has a set of optimal independent operations. The contract should be independent of underlying implementation details, language constructs and logic of the system.
Web Services and WSDL
In Web services, WSDL is the contract defining language. Contract-first doesn't necessarily mean writing WSDL using a notepad. Many tools are emerging with WSDL auto-complete features, as well as tools that plug into your existing development environment and auto-generate WSDL.
There is a hybrid technique where you begin by defining the service as a Java interface, keeping out language-dependent constructs and underlying implementation. You must take care to use input/output parameters of operations that are precisely definable using XSD. Then you can use the Java2WSDL tool to generate the WSDL or the contract of the service. Java2WSDL tool is under Apache license and comes as a part of Axis2 tools. This technique works well for a contract-first design as long as the interface does not include language specific constructs.
Conclusion
A contract-first approach has many advantages over a code-first approach. A good contract contributes to loosely-coupled and reusable services and promotes SOA. A code-first approach is only good for the situations where initial project productivity is the main concern. The contract-first approach itself does not yield a good contract; it must represent an active collaboration with all involving parties, and it should hide the underlying implementation details.
References
[1]https://searchsoa.techtarget.com/news/article/0,289142,sid26_gci1044083,00.html