What is an API contract?

An API is a promise between the API provider and its consumers.

When a consumer requests information from a provider, the provider promises to respond with that information. Of course, there are certain rules governing this interaction. For example, how to identify the requestor, how to determine whether the requestor can access the requested information, how to format the request in a way that the server will understand, and how the server should format the response in a way the requestor can consume

API contracts are primarily relied upon by developers on both sides. Requirements might resemble the following user stories:

• As an API consumer, when I send an improperly formatted request to the API provider, I want to receive an error response that describes why my request did not match the API contract, so that I can amend my request and resend it.
• As an API consumer, when I send a properly formatted request to the API provider, I want to receive a response according to the API contract, so that I can understand the response and incorporate it into my application.

In practice, the user stories would be a lot more detailed and complex. At a minimum, an API contract outlines details such as the API's endpoints (the specific URLs or locations to send requests), the format of the requests and responses, the data models used to structure the data, and the mechanisms for authenticating and securing access to the API. An API contract formalizes all of this information into a single technical specification that both parties can rely upon.

Business requirements and user stories often do not provide enough fidelity to fully describe a technical specification so developers turn towards more bespoke interface definition languages such as OpenAPI (formerly known as Swagger) to describe the API contract. Interface definition languages provide such high fidelity that they can even be used to generate client and server code, accelerating development on both sides.

How is an API contract different to documentation?

Much like legal contracts, API contracts are focused on eliminating ambiguity, miscommunications and misunderstandings. As a result, they tend to be highly technical and are best used as reference material when specific points need to be clarified.

For a developer trying to integrate against an API, if they only have the API contract they will likely ask, "Where do I start?". API documentation exists to help the developer integrate against the API.

Documentation should contain material to help the developer get up and running as quickly as possible or help the developer utilize the API for specific use cases. It typically includes conceptual overviews, tutorials, code samples, best practices, and other supplementary information. It may also include explanations of business logic, use cases, and additional resources.

While API contracts prevent misunderstandings, documentation actually helps build understanding.

Commercial APIs have other types of contracts

All APIs should have an API contract between the API provider and the consumer. Commercial APIs, that is APIs sold to external customers, usually have other kinds of contracts that are important to know about.

Terms of Service (ToS): For SaaS products, public APIs and especially APIs with self-serve developer access, there will usually be a Terms of Service agreement. This is the main legal contract between the provider and consumer and covers aspects such as permitted use, restrictions, intellectual property rights, liability disclaimers, termination clauses, and dispute resolution mechanisms.

Developer Agreement or API License Agreement: These agreements are specifically tailored for developers who will be accessing and using the API. Similar in scope to the Terms of Service agreement, provisions in these agreements are more tailored towards API usage than general product usage. As an example, here is Zendesk's agreement.

Service Level Agreement (SLA): An SLA defines the performance obligations of the API provider. While an API contract is scoped to individual requests and responses, an SLA is scoped to many requests and responses over the entire period of the agreement. Common SLA metrics include uptime guarantees, response times, availability thresholds, and support levels. While you might hear metrics such as "99.9% guaranteed uptime", it is important to define metrics in much greater detail since violations of SLAs can result in financial penalties for the API provider.

Data Usage Agreement or Data License Agreement: If the API involves the exchange or use of data, a data usage or data license agreement may be necessary. These agreements govern the rights, permissions, and restrictions related to data access, usage, ownership, sharing, and protection. They typically address issues like data privacy, confidentiality, compliance with data protection regulations, and intellectual property rights related to the data.

Partnership or Reseller Agreements: In some cases, API providers may enter into partnership or reseller agreements with third-party companies or individuals who will incorporate or resell the API as part of their own products or services. This is common with "aggregation" APIs - APIs that provide a simple, unified facade to multiple backend providers. These agreements outline the rights, responsibilities, revenue-sharing arrangements, branding guidelines, and other terms governing the partnership or reseller relationship.

Non-Disclosure Agreement (NDA): An NDA is uncommon for public APIs where ther are many consumers using one API product. However, for a partner API or an API that is built as part of a custom project with a client, an NDA may be required to share sensitive or proprietary information during the development process with the other party.

End-User License Agreement (EULA): If the API is incorporated into an end-user-facing software application, an EULA may be necessary. This agreement governs the terms of use, licensing, and restrictions placed on end-users of the software application, which includes the integrated API functionality.

Summary

An API contract defines the expected programmatic interactions between an API provider and consumer. It outlines the rules, requirements, and expectations for using an API from a technical point of view.

The relationship between an API provider and consumer is not just programmatic but often encompasses legal and commercial aspects too. These aspects are defined in other kinds of agreements such as licenses or SLAs. While such agreements may be referred to as "contracts", the phrase "API contract" typically refers to the technical specification used by developers.

Since API contracts are highly technical and detailed, they are often written by developers themselves. A tool like Criteria can accelerate this writing process while making it accessible to other people such as product managers, ensuring that the API contract meets business requirements as well as being technically sound.