Contract-First Development

Get agreement upfront when creating reusable services
Contributed by

Jim Barton

Roman Martin

Published June 20, 2019

What Is Contract-First Development?

Contract-First Development is about making your intent clear across team members, external teams or 3-party systems. By using tools like OpenAPI (for synchronous interactions) or AsyncAPI (for asynchronous interactions), we can define our programming API clearly at the outset. We also update the "contract" before we implement changes to the code. Further benefits include:

  • Code generation for both clients and servers
  • Automated testing and validation tools
  • Simple mocking of the service under development
  • More relevant and current documentation

Why Do Contract-First Development?

So that everyone can be productive in parallel AND we can have strong guarantees of the resulting applications working together properly. Instead of UI development being blocked awaiting a working service to code against, UI and Service developers can work in parallel. Also, if you define the contract first when developing or changing API interfaces, you have a clearer "Definition of Done" and "Acceptance Criteria" for the work.

How to do Contract-First Development?

In case of synchronous interactions, basically HTTP and REST endpoints, OpenAPI provides many references:

In case of asynchronous interactions, very typical in Event-Driven Architectures or Messaging systems, AsyncAPI provides many references:

Look at Contract-First Development

Links we love

Check out these great links which can help you dive a little deeper into running the Contract-First Development practice with your team, customers or stakeholders.

Except where noted, content on this site is licensed under a Creative Commons Attribution 4.0 International license. This site is graciously hosted by Netlify