Designing by software is a contract – like a legal or business contract. When we design software by contract it means we are designing against a specific specification for each software component. The specification should include things like the abstract data types, preconditions, postconditions.
Bertrand Meyer coined the phrase in the mid-1980s and mentions it in in his book Object-Oriented Software Construction.
What is Designing APIs by Contract
SOAP or XML based webservices require creating a WSDL or “Web Service Definition Language”.
We then take the WSDL file and can generate class files to use to request or receive data from the API.
For REST API development, there’s an optional specification that can be used called the OpenAPI (formerly known as Swagger). An OpenAPI document can be generated in JSON or YAML.
Benefits of Designing APIs by Contract
Designing upfront doesn’t come easy, but there are definitely benefits to it when working on a REST API. If we don’t do some upfront design, we’ll end up with a lot of different major versions which can be difficult when creating a REST API. The blog article Versioning in REST APIs talks about some of the different approaches for versioning and when to add a new major version.
Developers Know What to Expect
The client and provider explicitly know what each others expectations are. Stub software can be used to mock each other’s behavior based on the contractor.
Developers Can Work in Parallel
The client and the provider are very clear about details and what can happen – develop can happen at the same time as integration if stubs are being built as part of the planning stages.
Encourages Reusability
in an API that has a contract it’s very easy for the service to have repeating parts and encourage reuse.
Client Code Can Become Generatable
With SOAP (WSDL), and REST (OpenAPI) based APIs it’s possible to generate the classes and libraries that are used to call the API.
Work Can Be Easily Outsourced
When an API has a contract it become easier to test, and a lot of the specifications should already be well designed. With a waterfall approach it becomes easier for an offshore company to provide accurate estimates and costs.
Disadvantages of Contract First API Development
There are very few disadvantages to Contract First API Development, but there’s a very big disadvantage. To properly do API development with a contract, you need to plan and create the contract up front.
Upfront Work Required
The majority of the design work needs to happen before any development can begin. If the effort isn’t put in at the front of the process all stakeholders will likely be impacted. A proper approach to communicate changes to all consumers has to be done.
This results in at least a sprint 0 needing to be done OR the waterfall approach needing to be done.
Wrapping It Up
Designing by Contract can be challenging, and require quite a bit of upfront effort but there are lot of reasons to look at doing it such as:
- Developers Know What to Expect,
- Developers Can Work in Parallel,
- Reusability is encouraged,
- Client Code Can become Generatable
I’ve written quite a bit about API development and integrations. I highly recommend spending a bit of time upfront (“sprint 0”) because the benefits far outweigh the downsides.
