How I'd decide to build on an API

A great analogy for a data contract is an API. So, let’s walk through how I’d decide if I want to build something important to me on a particular API.

Imagine I’m implementing with a payment platform to take payments on my website.

The platform has APIs and at the minimum those API endpoints each have a schema associated with it (or 2, the request and the response schemas).

With that schema information alone I could probably work out how to integrate with the platform, although it wouldn’t be easy. So I’d like some documentation about each endpoint and how they work together so I can build a complete integration.

But taking a step back from the implementation, before I can trust this platform to handle my payments I want to know if this API is stable.

So I’d like to see a version number, and I’d like a guarantee that if a breaking change needs to be made and a new version created there will be a change management process followed, with a migration path, enough time to move over, etc.

Although really I would rather it didn’t change often, as migrating is work for me that brings no direct value to me. So, I’d certainly choose a platform that prioritised compatibility (as boring as that is).

Then, how is this platform going to perform over time? What are the SLAs they are guaranteeing? Do they meet my requirements?

What happens when the SLA is breached? Is that reported on a status page, so I can see how well they are meeting it?

I’d need all of this information before investing in integrating with a platform provider.

I’d need all of this information before investing in building an important application on a dataset.

The data contract contains all of this information.