In my previous post, I talked about the the characteristics of the API First approach and showed you a very basic example by using OpenApi and Spring Boot. Today, I will introduce another technique or technology you can integrate in your API to increase its quality and take even more advantage of the API First approach: the Consumer Driven Contract.
Contracts in APIs
In the APIs’ world we can easily recognize two different stakeholders, the consumer and the provider.
On the consumer side we might have a website or mobile app which uses the API to fulfill their requirements. The software developers who «consume» the API use its documentation to learn how it works and be able to integrate it. They need to understand what kind of requests, input parameters, http status codes etc. the API accepts.
On the other hand, provider refers to the backend or API itself. The producer provides an API to fulfill the requirements of one or more consumers, whom it doesn’t need to know beforehand.
The consumer and provider need to somehow understand each other and this is when contracts come into play. A contract defines how the communication between the two parties has to take place – in other and more technical words, a contract is a request-response pair that has to be fulfilled by both parties.
We can define one or more contracts for each endpoint (the more the better) and at this point you may wonder why you should invest such amount of time on something that probably doesn’t add as much business value to your API as you would like. Please keep reading.
Advantages
One of the biggest advantages of contracts is that they can be written on a very early stage of development – even if you haven’t written any line of code in your API. This is because the only thing you need for it is an already defined OpenApi (or Swagger) specification.
As I mentioned above, a contract defines how the communication between a consumer and a provider has to take place. For example:
- Contract A: When consumer sends GET /greet-me the producer has to say «hi there»
- Contract B: When consumer sends GET /greet/{name} the producer has to say «hi {name}!»
What is the different between that and integration tests? You are right, contracts can also be used to generate Rest-assured tests for your API! When I said “the more contracts, the better”, I meant that you will increase your code coverage significantly if you write the proper contracts. This way, we can work according to the TDD (Test Driven Development) process, implementing first the tests that will fail on a first instance, and afterwards the application itself to make the tests run correctly.
Another great advantage of contracts is that, since they define an API’s behavior, there are mechanisms to use them to provide Mocks. How does it sound? You will be able to mock your API without having implemented any of the endpoints. This way, you could deploy the mock to a development environment so that the consumers can start with the integration, and at the same time you can start with the actual development of your endpoints.
Disadvantages
There are some more points that we need to consider before deciding to write contracts.
A contract defines the behavior of the API, which means that you will increase the couple of your code with external consumers during the build phase.
If you implement contracts on an early stage of development, you have to be pretty sure that your OpenApi specification has been designed carefully, otherwise you may introduce changes into your development which may break the contract.
Writing contracts means an additional effort. If you want to provide a high quality API you need to write contracts – not only for the happy path, but to cover all the edge cases, that is, all the possible error codes that your API can return.
Summary
This is what can be deduced when using contracts:
- Increase of the quality by generating REST-Assured tests
- Possibility of parallelizing development on the producer side and integration of the consumer side by generating Mock stubs.
- Implementation of contracts requires additional effort
- … and also a very well designed OpenApi or Swagger specification to avoid changes that break the contracts
In the following posts, I will apply this technique to a very basic API to show you how you can generate Wiremock Stubs and Rest-Assured tests by using the Spring Cloud Contract Verifier plugin.
I hope this helps you to decide if you could integrate contracts in your project and make use of their advantages to provide very high quality APIs.
See you on next posts!.
