These are the properties we've identified as being the most common properties applied as part of API operations, providing the building blocks needed to onboard consumers--the goal is to not just identify them, but transform from being human-readable to machine-readable to help automate and scale the API economy.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
