Design-first API Contracts: Key to accelerating Integration and Improving API Quality

Service specifications along with developer documentation are key to turning your APIs into products. A well written and standards based API contract can not only make it faster and easier to integrate but also to test and deliver a solution faster

Good API contracts help improve key software delivery metrics such as lead time through collaborative/iterative design, increase deployment frequency of integrated components and reduce time-to-market for distributed software solutions

Contracts Generated from Code (Old Way)

API contracts are created and exchanged in IT projects when developing system integrations and  these contracts contain details about protocol, headers, content type, operations, information exchange, errors etc.

It natural then when dealing with commercial-off-the-shelf systems to get “pre-generated” out-of-the-box contacts however this process extends to any customizations we make on these products and we get into a habit of writing code first and then generating a service specification from it. Contracts generated from code-first were the norm earlier, especially when building SOAP services where WSDL was generated using tools from code


The generated contract creates a dependency on the service writer and generator before consumers can use a contract. There can also be multiple copies of the contract – the actual (runtime) and the shared (copy)

Generating a contract

We find that traditional generated contracts are well suited for COTS application integration projects  but more modern (software) delivery practices especially around digital / customer channel experience APIs and  APIs-as-products (from business capabilities) rely on design-first approach with APIs hosted on a API portal with rich documentation etc. Contacts can also be pre-written i.e. through a design process they can be documented as a “this is how we will provide the service” specification

Design-first API Contracts (Accelerates Integration Time & Quality)

The design-first API contract creation approach has the consumer and provider come together to create a definition with the provider quickly generating mocks and the consumer writing tests

Collaborative design of API

Designing APIs with consumers through mocks and contract tests leads to low integration defects and reduced system integration testing (S.I.T) time and faster time to market


The opposite to this contract-first practise is no-contract or contract-after-development practice which delays the delivery pipeline in multiple ways

  • slow to test: it makes consumers wait until the producers have finishing writing their code, essentially making the process sequential. during integration testing changes are equally sequential, this cycle can be long in large complex projects where new teams across vendors are working together
  • slow to build: this process is not collaborative and does not suit scenarios where services are designed by consumer and provider teams together


In summary, generated service contracts are documentation and provided after code for service is created. This makes it less collaborative between providers and consumers of a service and in large complex deliveries this can lead to poor API quality and longer lead time to integration

Tooling cannot solve this problem, it is cultural. For example, automating your CI/CD pipeline to generate API contract from code is still poor practice. Design-first and then code. It is important to get into the habit of writing APIs in plain text using a markup language or using tools such as Swagger or RAML designers. The process of design must extend to sharing the design, creating mocks and working with consumers and other teams to share the design, seek feedback, iterate until the API is well socialised and understood

API design first is a shift in engineering culture and leads to accelerated integration solution delivery and a quality product

Leave a Comment

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s