Designing APIs by Contract

Sharing is Caring

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”.

Example: SOAP WSDL generated from Salesforce

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.

Sharing is Caring

Brian is a software architect and technology leader living in Niagara Falls with 13+ years of development experience. He is passionate about automation, business process re-engineering, and building a better tomorrow.

Brian is a proud father of four: two boys, and two girls and has been happily married to Crystal for more than ten years. From time to time, Brian may post about his faith, his family, and definitely about technology.