What is an API contract?

When building and consuming APIs you will often hear of a “contract”. What is it? Basically an API contract is a document that describes how the API works. Yep that's it. But it's importnat to know that it's also an agreement from API developers that the product they put out works how they say it does. Any changes to the API should be reflected in the contract otherwise anyone who consumes it will not be aware.

An API contract is the documentation that describes how the API works and how it should be used.

Why is an API contract needed?

When making changes to an API those changes should be communicated out and documented to avoid unexpected behavior from clients that consume it.

Imagine you have an app that depends on some data from an API. Let’s say the API developers decide to rename a field or the type of response your client application will break.

API versioning is a tactic for making breaking changes to an API. For example the api endpoint https://myrecipes.com/api/v2/recipes represents that this api is on version 2. This also allows us to assume there is a version 1. Clients can continue to use v1 and not have their app break. Newer functionality can be developed on v2 or v3 etc.

What does an API contract look like?

There are many forms of documentation for API contracts. Stripe’s API documentation is an amazing example of how an API contract should be done, but not every API can have the resources to create that.

Swagger is a popular solution for supporting API documentation. This Cat Store example shows how even some basic information like GET, POST, PUT and DELETE methods can go a long way in explaining the functionality of an API.

Conclusion

API contracts are a document that describes your API. As an API developer it’s important to make sure your API contract is up to date and accurate for anyone consuming your API.