APIs.json Properties

These are all of the properties we encourage API producers to include in their APIs.json indexes. They are based upon the common building blocks of leading API providers, and are what API consumers have come to expect when it comes to API experience.


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.

GitHub Organization - A GitHub Organization is commonplace for larger more organized API producers, establishing a place where you can find SDKs and other code used for integration, but also machine-readable artifacts, issues, discussions, and other useful outputs from everyday API operations that will help provide nutrients for an API ecosystem.

GitHub Repository - GitHub repositories are great for making SDK and other artifacts developers will need to put an API to work, but you can also publish OpenAPI, examples, and even run your entire API portal using GitHub pages. A GitHub repository has proven itself to be an essential building block of any public API program, and powers API Commons.

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.

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.

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.

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.

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.

Webhooks - Webhooks are a way to communicate between applications by sending data to another application when an event occurs. Webhooks are HTTP-based callback functions that are automated and triggered by an event in a source system, then sent to a destination system, providing event-driven capabilities utilizing simple HTTP "reverse APIs".