---
published: true
layout: post
title: Expanding the Definition of Our API Contracts
tags:
  - Contracts
  - Business
  - Technology
  - APIs.json
image: >-
  https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-factory-road.jpg
---
In recent years we’ve begun collectively using the phrase "API contract" to often describe the OpenAPI or AsyncAPI for our APIs. While I have been complicit in the adoption of this phrase, and support its usage anytime I can, I also feel that it also reflects much of what is deficient with the API Economy. I agree that an OpenAPI represents a contract between producer and consumer, but I am painfully aware of how this represents just the technical side of this contract, and much of the business side of things is taken for granted or not addressed at all.

As a potential consumer of an API, is it enough that I the API producer only publish an OpenAPI and share that with you? No, of course not. At the very least, as a producer of the API, I should generate documentation from the OpenAPI, or maybe a Postman Collection and share that with you too. If the producer and consumer of an API have a healthy relationship, we may also treat the OpenAPI as a sort of truth for what you can do with the API. If I do this, I would adopt a semantic or date based versioning strategy, then be more thoughtful about managing and communicating change for the API, further strengthening our use of OpenAPI as a contract. Is this all that is needed—-no, this perspective still takes a lot for granted.
<img src="https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-new-building-start.jpeg" width="100%" style="padding: 15px;">
As an API producer, I will need to publish my OpenAPI and generated documentation to a portal that my consumers have access to. Then I need to provide a way of onboarding consumers, allowing them to sign up for the API and access a token-—something I can define in my OpenAPI using security definitions, but not entirely unpack how you will onboard. I will also need to provide a sandbox, SDKs, code libraries, as well as some support mechanism and feedback loop. I can go on and on with this... There is much more than the OpenAPI needed to establish or define a contract for my API. If I provide an API, OpenAPI, and documentation, but don't tell you how to onboard and access the API, it doesn’t mean very much. Additionally if the API is not secure, or does not perform as expected by API consumers in a reliable manner, then my contract doesn’t mean much, does it? OpenAPI doesn’t describe any of this.

These missing building blocks of our API contracts are what we are trying to respond to with [APIs.json](http://apisjson.org) and the [API Commons](http://apicommons.org). With these projects we are mapping the existing known API landscape defining the properties of API operations used by leading API providers across every industry. We are doing this in the service of building the [APIs.io API search engine](https://apis.io) using APIs.json, but in reality, we are also populating the API Commons with common and community properties, as well as vendor overlays, base APIs, and blueprints from leading API producers. I see a complete APIs.json as more than just an index for API discovery, I see all the fingerprints of a contract between an API producer and API consumer, and also between API product, API engineering, and potentially an API platform team. I see the properties of API operations present in a robust and healthy APIs.json as much more than just about API discovery, and more about a contract between all the stakeholders involved.
<img src="https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-public-market-fish.jpg" width="100%" style="padding: 15px;">
The [APIs.json for APIs.io API](https://github.com/api-evangelist/developer-portal/blob/main/_data/apisjson.yml), or for [AWS](http://apicommons.org/base/amazon-web-services/), [eBay](http://apicommons.org/base/ebay/), [Stripe](http://apicommons.org/base/stripe/), or [Twilio](http://apicommons.org/base/twilio/), all reflect more of the big picture of what occurs between API producer and consumer than what a single OpenAPI can define. OpenAPI provides the technical details, and APIs.json indexes that, plus all of the rest of the business details. These are still incomplete contracts. Well, except for Apis.io. I have what I’d consider to be the complete APIs.json contract for APIs.io, reflecting the relationship between API producer and consumer as well as product, engineering, and platform on the producer side of things. This demonstrates two ways my definition of an API contract goes beyond the current mainstream definition, 1) an API contract MUST contain both technical and business requirements, and 2) an API contract must be negotiated between not only producer and consumer, but also between all the business and technical stakeholders on the producer side—-something that will vary from enterprise to enterprise.

APIs are ubiquitous. Many of the building blocks indexed by APIs.json and used to power the APIs.io search index are ubiquitous properties of public API operations across many industries. These building blocks of APIs act as the ad hoc and often organic elements of function (or not so functioning) API contracts between API producer and consumer. You see hints of these building blocks emerging in government regulation of APIs. The governing bodies behind PSD2 for payments in Europe, and at the CFPB governing payment regulation in the US, all realized you can’t just dictate only the API, you have to also enable access via portals and documentation, performance and testing, and other important elements of our API operations. All of these needs won’t just magically go away with artificial intelligence. You can magically abstract the business relationship required to tap into one or many enterprise digital resources. You can’t wish away copyright, patents, and other intellectual property. These all have to be present in a digital machine-readable contract that governs all interfaces that are applied.
<img src="https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-seattle-shipping-people-walking.jpg" width="100%" style="padding: 15px;">
I wanted to take a breath in my work and make sure that the API contract for the APIs.io API reflects my vision of API contracts. I still have more work to do on some of the properties and overlays before I’d consider v1.0 of the APIs.io API contract is ready, but I have the North Star of what I want in my mind's eye now. At face value most folks will see APIs.io as simply an API search engine, when in reality that is just the facade. It is really a large blueprint for the language we need to define the API contracts driving business today, then refine it all so we can stop competing on the most common aspects of API operations, and begin investing in what is actually needed to power what is next in a scalable and sustainable way. API search with APIs.io and API discovery with APIs.json is just the part that 95% of people will see. However, for me it is the common APIs.json properties, combined with the existing momentum of the community properties published to API Commons that will become the vehicle we need to scale and automate all of this. It is these properties, combined with vendor overlays, base APIs, and healthy blueprints to follow that will help us standardize the community API platform to property power the API economy.