API industry thought leader and API governance expert, Kin Lane, has been writing about expanding the definition of API contracts. His pieces made me revisit Platformable's model of how an open ecosystem generates and distributes value to consider: where would API contracts fit into the model?

What is an API Contract?

My first introduction to understanding APIs as contracts was from Mehdi Medjoaui in 2014, when he wrote: "From a legal perspective, an API is a contract between you as a supplier and your customers. This is defined in an API Terms of Service and Business Model Agreement." Mehdi has since gone on to focus on the API Terms of Service part of this definition, building out the APIToS template and Wizard tool (with our help at Platformable) to provide a standard, easy-to-understand contract that defines for API consumers what they can do with an API and the data that passes through it, and how changes will be communicated in future.

Often the term API contracts is used ro refer to the API Specification file (such as an OpenAPI Specification or AsyncAPI). The problem, as developer Poornima Nayar pointed out in her blog, is that a specification file "is very 'developer-ey' in the technical documentation language world and also something that is way too coupled with your API".

Kin's current thinking is focused on addressing this disconnect between the technical developer specification and the business value and context of using the API. He sees API contracts as a way to bridge this specification with the API Terms of Service approach, as well as include an outline of the resources and means of business interaction that API users can expect to receive from using the API. He suggests an extended model for a machine-readable API contract would include:

• The specification
• Descriptions of copyright, patents, and other intellectual property (as discussed in the APIToS model for example)
• Agreements on how versions and other changes would be made and communicated
• Performance and security service level agreements; and
• What resources such as SDKs, sandboxes, support mechanisms and so on will be made available.

At Platformable, we will draw on some of Kin's work to define an API contract:

An API Contract in an ecosystem

Given Kin's approach, an API contract could play a key role in defining how an API consumer can participate in the API provider's ecosystem.

At Platformable, we see there are multiple ecosystem levels:

At an industry level, there is a global open ecosystem where standards are used to enable interactions globally to build digital products and services, automate processes, share data and so on. We see this emerging predominantly in supply chain management, travel, and intellectual property at the moment.

At a regional or country level, there is often an national industry ecosystem governed by regulations or enabled by open standards that support market participants to exchange data, build digital products, and so on (we say regional and country because for example, some regulations operates across all of Europe, and some API standards like FDX and UPI are being used to enable participants to compete, co-create and/or collaborate across countries). We see this predominantly in banking/finance, and health at the moment, as national regulations define the playing field, although there is also some crossover especially in finance where market barriers are falling to enable competition and collaboration at the global open ecosystem level.

At an entity level, an ecosystem is the network of participants that make use of an entity's APIs. For example, all of the businesses that build solutions using a single bank’s APIs, for example, are part of the bank’s ecosystem.

In other words: It's ecosystems all the way down!

For this analysis, we are talking about this final ecosystem level: an API provider is an entity that has APIs, and the API contract defines how API consumers can enter and participate in that API provider's ecosystem¹.

The role of API Contracts in enabling ecosystem value

When we look at our open ecosystem value model, Kin's suggestion of a more complete API Contract encompasses the full set of components we describe that exist between an API provider offering an API, and the use of that API by an API consumer who then builds digital products or services, or creates workflows, and so on, from the API. In our ecosystem model, we have been referring to this set of components as “value enablers”:

Our value model shows that between the provider providing and the consumer consuming is a suit of value enablers. That is, the ability of the provider to scale their APIs and build out their own ecosystem, and the speed and confidence with which API consumers can build with the API, is mediated by the following value enablers:

• Developer Experience: the resources made available to API consumers to assist them to onboard and build successfully with an API. Building on our initial work writing for ProgrammableWeb, our work with World Bank on financial inclusion APIs and our work with European Commission's Joint Research Centre on API Discoverability, we have identified 15 key developer resources that significantly impact the ability of developers to programmatically make use of an API
• Security and Privacy: The level of security and privacy robustness of an API, and its ease in enabling data protection regulatory compliance and use of security best practices impacts the overall trustworthiness of an API and the willingness of API consumers to use in production
• Digital Readiness: Digital readiness refers to the level of skills and expertise amongst potential API consumer sub-sectors to make use of APIs, and also to the digital readiness of end consumers to make use of digital products. For example, in banking/finance, for a fintech to decide they want to use a bank's account information API to enable their customers to integrate their bank account info into the fintech app requires two types of digital readiness: the fintech needs to have a developer team that is capable of integrating APIs into app code, and they need to have a consumer base of app end users who would make use of this feature and understand the value it offers.
• Industry Velocity: Thanks to Kin for pointing this out. This is the overall subsector or industry's willingness and capabilities to move to API-enabled architectures. To continue with the fintech app example, industry velocity occurs when the fintech needs to start integrating APIs because it is a standard feature expected of fintech apps, or perhaps industry velocity is being harnessed by regulators who make sandboxes readily available, provide funding support, or that publishes templates and blueprints that help build API capabilities across the whole industry.

API provider-focused components of API contracts

In addition to these value enablers, other components will have already influenced the design of the API: 

• Standards for example, may have been incorporated into the API design 
• Ideally, data governance work will have occurred to create standardised data models that are reflected in how the API calls and exchanges data. 
• Where regulations require specific API capabilities or components to be included, this would also have influenced the API design.

So an API contract then, if it is published by the API provider, makes clear how the API consumer understands the context around all of these components described on the left/provider side of the model:

• The role of regulations
• The use of standards and data models
• The availability of developer resources
• The way security and privacy is addressed.

In some cases, API providers may not be keen to become too opinionated on the regulatory or standards environment, but in some sectors like banking, health and supply chain management it would be challenging to define ecosystem participation without at least a nod to the governing regulatory and standards context and how that has been addressed in the design of the API.

API consumer-focused components of API contracts

In our diagram, we also show the API contract as being two halves: the definitions clarified by the API provider, but also the API Terms of Service clauses that explain the rights and responsibilities of API users which may clarify:

• Use of patents, and intellectual property
• Valid business use cases
• The rights of users to understand changes and version control as it occurs.

A complete set of components for an API contract 

In an open ecosystem, an API contract could act as the guide for ecosystem participation. In summary, an API contract would describe:

• What regulations govern the use of the API
• What standards and open data models the API recognises
• What developer resources will be made available to the developer to support them in using the API
• How security and data privacy will be managed in the API
• Who owns the intellectual property and patents of the API and how they are used
• What use cases are permitted to be created using the API and what is not allowed
• How developers will be informed of changes to the API and how version control will be managed.

Kin’s work on API contracts is growing, and we encourage readers to keep an eye on the API Evangelist blog (or follow Kin on LinkedIn) to keep up with his thinking. We have updated our ecosystem model and work on ecosystem participation practices to more clearly include the API contract approach.