Member-only story
How To Ensure Reliable Inter-Service Communication With Contracts
Leverage several open-source tools to prevent breaking changes between your services
You’ve just deployed a change to an API that your team owns, that’s used by several internal clients. All the tests were green, but when deployed, several of the clients’ integrations suddenly started to produce errors!
In the API world we live in, this is an extremely common scenario. There are some techniques we can use to help detect issues between services sooner, and they come in the form of contracts.
What Are Contracts?
In the business world, a contract defines how two companies are going to do business. They both set out terms and come to an agreement — company A will provide company B with X, and company B return Y to company A.
The same is true for software, just on a smaller scale (and typically with far less writing!). Implementation will vary depending on the programming language you’re using, but in most modern languages they typically take the form of an interface.
Similarly, in the business world, contracts can be broken. If you change the return value of a method from an integer to a string, then you’ve broken your contract with any clients, and there’s a reasonable probability that your application may now break.
In statically-typed languages, such as Java, the type system enforces these contracts — if you made the change described above, it wouldn’t compile because the calling class would be explicitly expecting an integer.
Getting quick feedback that something is broken is vital. That quick feedback will lead to fewer bugs, quicker development, and it makes it easy for other engineers, who’re not familiar with a particular codebase, to understand what’s happening.
That’s all well and good for development on a single service, but how can we leverage contracts between two or more services?
Defining Contracts For HTTP APIs With OpenAPI
The OpenAPI Specification, formerly known as Swagger, has been around for almost 10 years. It’s typically used with REST APIs, but…
