WSO2 is now Choreo LabsLearn more

Trusted AI Governance
Build

Create agents and AI apps with the tools and languages your teams already use.

Connect

Link agents securely to your APIs, data, models and business systems.

Run

Deploy, observe and operate agents and AI apps reliably at any scale.

Govern

Control identity, access, cost and policy for every agent in production.

Agent Management

Developer Platform

  • API Management Cloud

    Design, secure and publish APIs with governance and analytics built in.

    Sign Up Now
  • Integration Cloud

    Connect apps, data and AI agents with low-code and pro-code integration.

    Sign Up Now
  • Identity & Access Management Cloud

    Secure sign-in and access for customers, partners, workforce and agents.

    Sign Up Now
  • Agent Management Cloud

    Build, run and govern AI agents with full visibility and control.

    Sign Up Now
  • Developer Platform Cloud

    Ship cloud-native apps faster on an internal developer platform.

    Sign Up Now

Self-Hosted

Full control over your stack. Deploy directly to your own servers, bare metal, cloud, or Kubernetes environment. Your data never leaves your perimeter.

Product Downloads
Choreo Labs
AI Governance
Platform
Solutions
Resources
Article

Contract-first design

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