Common API Properties
The most widely used properties across API operations — identified, described, and made machine-readable so they can be used to automate and standardize the API ecosystem. These properties work directly with APIs.json indexes.
Authentication
Authentication is essential for most public APIs and is often the most common point of friction when it comes to onboarding with an API. This API Commons property is often a human-readable affair, and will need to become something that is machine-readable if we are going to scale things.
View
Blog
A blog is an essential communication tool for any API operation, providing a simple self-service way for API producers to keep their consumers up to date on any changes. An active blog is a quick way to get up to speed on what an API does and can easily be syndicated via RSS or Atom feeds, and can be used to broadcast to social media.
View
Change Log
Communicating change is important for any API provider, and having a simple and up-to-date log of what has changed is a great way to make change self-service. Your change log doesn't have to be verbose, but should be accurate and provide as much useful detail for consumers as possible.
View
Chargeback Policy
A ChargebackPolicy property references a document describing how an API provider or internal platform allocates and recovers costs across teams, cost centers, or business units — including chargeback (actual cost transfer) and showback (visibility without transfer) methodologies. Chargeback and invoicing are formal capabilities in the FinOps Framework. Publishing a chargeback policy makes internal billing transparency discoverable, especially important for platform APIs used across multiple organizational units.
View
Contact
API providers should be afraid to make contact information to consumers, making it easy to access a contact form, email address, or other way to contact. Contact information is often replace with forums and other self-service way to engage with a community, but nothing replaces a form or email.
View
Deprecation Policy
Every API will eventually be deprecated, so having a plan and communicating the deprecation policy with consumers via a dedicated page makes a lot of sense. This page will help API providers think a little bit about the future, and establish some guard rails and channels for communication with consumers.
View
Documentation
A reference to the human readable documentation for an API, that describes the surface area of an API with all the details consumers need. This documentation may or may not be generated from an OpenAPI or other machine-readable artifact, but is published as HTML or Markdown, and mean for human consumption when onboarding with an API.
View
Error Codes
Providing a detailed list of error codes that API consumers can expect when integrating with an API, sharing common HTTP status codes, but also custom errors returned. Having a single page helps communicate errors with consumers, but it also helps producers evaluate how errors are handled across many different APIs.
View
Forums
Forums are a common way for developers to engage in a self-service way within a community. The forum may or may not be owned and managed by a platform, but almost always thrive when they are user supported, providing an opportunity for more advanced API consumers to answer questions and support the needs of newer API consumers.
View
Getting Started
Providing the basic steps of how an API consumer can get started using an API with as few steps as possible is essential for any API. Like other common properties, a getting started isn't just for API consumers to understand how to onboard, and it is about pushing API producers to simply and reduce friction when it comes to onboarding.
View
Integrations
Providing ready to go integrations with other APIs has become commonplace as part of Software as a Service (SaaS) solutions, and help demonstrate the value an API provides. Demonstrating how an API can be used with the existing platforms that API consumers are already using help make your APIs more useful and sticky for developers.
View
Interface License
Using the API Commons interface license to provide a legal position of the naming, ordering, and overall design of your API, not just the code or other parts. An interface license will help define the legal tone you take with how your API paths are able to be put to work within other applications and integrations.
View
Lifecycle
Breaking down the stages of the lifecycle across APIs, while also providing instances for individual APIs, with details of each stage, the policies and rules applied within each stage, and the progress that APIs are making throughout the lifecycle
View
Login
Providing what is needed for existing API consumers to login and access their accounts, keys, and other information regarding their API consumption. A login allows any consumer of an API to be able to access the resources they will need to make a decision when it comes to integrating, expanding, or deprecating their usage of an API, providing what consumers will expect.
View
Performance
Defining the benchmark for performance of an API, providing an overview of how performance is approached and what it means, while also providing actual tests, results, and other evidence that demonstrates that performance is taken seriously.
View
Policies
Providing the machine-readable policies that define the business aspects of API operations and how it is governed, breaking down the business and technical details of API operations in terms that help organize and make the governance of APIs approachable by business stakeholders and leadership.
View
Portal
Providing references to the relevant portal to an APIs operation, providing access to the landing page for the wider company, operations, as well as just for individual APIs when it makes sense--helping connect the wider ecosystem surrounding each API being delivered.
View
Pricing
Providing a machine-readable scaffolding to define the plans and pricing for APIs, and the common elements of each tier of pricing and access available. Pricing is not just about the financial aspect of access to APIs, it is also about which APIs you will have access to, and how much of a resource you can consume over time. Pricing is about enabling API consumers to have a plan for how they will use digital resources that is in alignment with a platform business strategy.
View
Privacy Policy
Breaking up the privacy policy into machine-readable, schema defined properties that allow for the legal side of an API to be understood programmatically. A privacy policy sets the stage when it comes to consumption, helping consumers with what they can expect when it comes to how their data and usage of digital resources will be shared or sold.
View
Rate Limits
All APIs should possess rate limits that govern the amount of any digital resource or capability a consumer be able to access, with well-communicated, consistent, and enforced rate limits. Rate limits are what give API producers control over their digital resources, and are a fundamental aspect of how any type of APIs is publicly made available.
View
Road Map
Providing visibility as far into the future as possible is a common trait of successful APIs. Maintaining, publishing, and consistently communicating around a road map helps bring alignment between API producer and consumers, providing an essential building block for managing change across any platform.
View
Rules
Providing an index of the machine-readable rules available for governing APIs, offering rules for linting API operations, as well as the surface area of each API, helping standardize how APIs are design, but also delivered across teams within an enterprise.
View
Security
The security of any API is important to producer and consumer, and no consumer should be using any 3rd party API platform that does not clearly communicate and demonstrate an API is secure. API security is a foundational business building block in any API ecosystem when it comes to building trust and keeping consumers integrated with an API.
View
Service Level Agreement
A service level agreement, or simply SLA, defines the level of service you expect from a vendor, laying out the metrics by which service is measured, as well as remedies or penalties should agreed-on service levels not be achieved. A SLA sets the tone between an API producer and consumer and can be communicated as part of API change management practices.
View
Sign Up
Where users can sign up for access to an API, providing what is needed to onboard in a manual or automated way, reducing friction in putting to work. Sign up or registration can utilize existing standards like OpenAPI or native solutions which help make it as easy as possible for consumers to manually or automatically sign up to use an API.
View
Software Development Kits (SDKs)
Providing code snippets, libraries, and full software development kits, or simply SDKs is considered standard operating procedure for APIs. Generating SDKs from OpenAPI has become common, and providing all of the top programming languages is expected by developers, making SDKs one of the essential API building block for any API operations.
View
Status Page
A status page provides API consumers with real-time information regarding the up-time and availability of each API being made available. Status pages often provide current as well as historical information regarding stability or outages, helping build trust with consumers over time regarding the health of an API platform.
View
Support
Offering a standardized set of API support for consumers to tap into helps ensure that onboarding is as frictionless as possible while helping build trust with consumers. Support can be as simple as email, or as structured as a ticketing system, but whatever is offered, it should work to keep API consumers taken care of throughout their journey.
View
Tagging Policy
A TaggingPolicy property references a document defining the cost allocation tag taxonomy for an API or platform — including required tag keys such as CostCenter, Environment, Product, and Owner, along with allowed values and compliance requirements. Cost allocation tagging is a foundational FinOps practice, and the FinOps Foundation publishes guidance on tagging policy compliance. Publishing a tagging policy makes cost attribution requirements discoverable by consumers integrating the API into their FinOps workflows.
View
Terms Of Service
Breaking up the terms of service into machine-readable, schema defined properties that allow for the legal side of an API to be understood programmatically. Providing a break down of what the legal constraints involved with putting an API to use will help consumers understand if it is a fit for their business needs.
View
Unit Economics
A UnitEconomics property references a document describing the per-unit cost model for an API — such as cost per API call, cost per gigabyte processed, cost per token consumed, or cost per transaction. Unit economics are a core FinOps capability under the Quantify Business Value domain. Publishing a unit cost breakdown alongside an API makes pricing structure discoverable by enterprise procurement, FinOps tools, and developers building cost-aware applications.
View
Use Case
. A use case corresponds to a set of resources and capabilities that API should perform in interaction with its consumers, and which produces an observable result that contributes with the goals of each individual API operation. Use cases define the business requirements which can be regularly aligned with the operational technical requirements defined as an OpenAPI.
View
Use Cases
Providing the who, what, how, and why of an API, establishing details about who the intended consumer is, while also linking use cases to specific operations to help align the business and technical details of an API.
View
Versioning
The details of how an API is being versioned with information about how change is being communicated with consumers across multiple channels. Having a formal approach to versioning published and communicated helps lay the ground work for change, but also keeps API consumers aligned with what has changed.
View