APIs.json

API Baseurl HTTPS info experience: security spec: apis

Each API baseURL should be an https URL.

API Contact Include Email info experience: documentationexperience: discoverability spec: apis

The contact object in an APIs.json file allows for referencing the email address of a person or group. This property provides a convenient way for users to seek support for an API, using email as the default method to reach the team managing the API in production.

API Contact Include Full Name info experience: documentationexperience: discoverability spec: apis

The contact object in an APIs.json file includes a full name (FN) property, which specifies the formatted text corresponding to the contact name in the vCard for an API. This provides a quick and clear way to assign a person, group, or other point of contact to an API for addressing questions and providing support.

API Entry Require Tag info experience: discoverabilityexperience: data-modeling spec: apis

Each API defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered by the API, highlighting its business value and the domain in which it is applied.

API Include About Page info experience: documentationexperience: discoverability spec: apisspec: properties

This property ensures provides a reference to an about page, either for the company, organization, or government agency behind an API, or specifically about the domain, team, and the APIs they produce.

API Include Contact info experience: discoverabilityexperience: documentation spec: apis

The contact object in an APIs.json file allows for associating a vCard that represents an individual or organizational entity. It includes common contact information such as a name, email, or other references, offering a standardized method for providing support for an API.

API Property Require Go SDK info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is a Go SDK available for an API, making it easier for Go developers to integrate an API into their applications.

API Property Require Java SDK info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is a Java SDK available for an API, making it easier for Java developers to integrate an API into their applications.

API Property Require Linting Rules info experience: governanceexperience: consistency spec: apisspec: properties

This property ensures that an API has governance rules applied, usually as part of a central set of governance rules, defined by policy, or stages of the API lifecycle.

API Property Require Node SDK info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is a Node SDK available for an API, making it easier for Node developers to integrate an API into their applications.

API Property Require Python SDK info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is a Python SDK available for an API, making it easier for Python developers to integrate an API into their applications.

API Property Require Road Map info experience: discoverabilityexperience: documentationexperience: governance spec: apisspec: properties

This property ensures there is a reference to the road map for an API or for the entire API operations within domain, line of business, or teams.

API Property Require Sandbox info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that an API has a reference to a sandbox for individual APIs or as part of common properties, providing sandbox, synthetic data, and mock servers for use in making test requests.

API Property Require SDK info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is an SDK available for an API, making it easier for developers to integrate an API into their applications.

API Property Require Security Page info experience: securityexperience: documentation spec: apisspec: properties

This property ensures there is a URL to the security page, providing details about how security is handled for an API.

API Property Require Signup info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures there is a link to where you sign up for an API, making sure API consumers can access in a single click.

API Property Require Status Page info experience: reliabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is a status page available for each API, providing the uptime status for any given moment, as well as historical data.

API Property Require Support Email info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that an API has email support, providing a valid email address that can be used to get API support.

API Property Require Support Issues URL info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that there are Git issues available to support an API, using the issues capability of GitHub, GitLab, or Bitbucket to support API consumers.

API Property Require Support Page info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that there is a support page available for an API, providing direct and in-direct support opportunities for each API or for entire API platform.

API Property Require Team info experience: governanceexperience: documentation spec: apisspec: properties

This property ensures that there is a reference to the team behind an API, providing a reference to business and engineering stakeholders.

API Property Require Terms Of Service info experience: governanceexperience: documentation spec: apisspec: properties

This property ensures that an API has a reference to a terms of service, covering the legal side of using an API.

API Property Require Use Cases info experience: documentationexperience: discoverability spec: apisspec: properties

This property ensures there is a reference to the use cases for an API, helping align an API with the who, what, how, and why of putting an API to work.

API Property Require Valid URL info experience: consistencyexperience: discoverability spec: apisspec: properties

This property ensures that properties of an API or API contract all have valid URLs, checking if any of the URLs are not properly formed, or could be other formats.

API Property Require Versioning info experience: versioningexperience: documentation spec: apisspec: properties

This property ensures there is a reference to how APIs are versioned, providing a single place where teams can learn about how change is communicated.

API Property Require Video info experience: documentationexperience: discoverability spec: apisspec: properties

This property ensures there is a reference to a video page or channel for an API.

API Property Require Vocabulary info experience: consistencyexperience: namingexperience: governance spec: apisspec: properties

This property ensures that there is a centralized vocabulary in use for guiding the creation and usage of tags, path segments, and other metadata associated with an APIs.

API Property URL HTTPS info experience: security spec: schemas

API property URLs (documentation, OpenAPI, etc.) should be https.

API Require Aid info experience: discoverabilityexperience: governance spec: apis

Every API should have a unique identifier, known as an AID (API Identifier). The APIs.json file, contract, or collection contains its own AID, which the API uses as part of its reference. Additionally, the API applies a slugified version of its name, resulting in a unique, human-readable identifier for the API.

API Require Base URL info experience: usabilityexperience: discoverability spec: apis

Each API defined within an APIs.json artifact can specify the base URL for the API. This URL serves as a reference point for developers during onboarding and when making API calls. Additionally, it helps identify the API and validate the domain it is associated with.

API Tag Require Upper Case info experience: namingexperience: consistencyexperience: discoverability spec: apisspec: tags

Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of every word in a phrase treated the same way.

Document APIs JSON URL HTTPS info experience: securityexperience: discoverability spec: document

The APIs.json url should be an https URL.

Document Include Business Impact Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Business Impact Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Business Model Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Business Model Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Capacity Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Capacity Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Customer Journey Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Customer Journey Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Domain Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Domain Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Event Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Event Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Locations Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Locations Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Rest Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Locations Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Include Value Proposition Canvas info experience: governanceexperience: documentation spec: collection

This ensures that an API has had the APIOps Value Proposition Canvas applied to the API, requiring that the canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.

Document Require Access info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `access` property.

Document Require Aid info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `aid` property.

Document Require APIs info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `apis` property.

Document Require Common info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `common` property.

Document Require Created info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `created` property.

Document Require Description info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `description` property.

Document Require Image info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `image` property.

Document Require Include info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `include` property.

Document Require Kind info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `kind` property.

Document Require Maintainer info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `maintainers` property.

Document Require Modified info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `modified` property.

Document Require Name info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `name` property.

Document Require Network info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `network` property.

Document Require Overlays info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `overlays` property.

Document Require Position info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `position` property.

Document Require Prompts info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `prompts` property.

Document Require Rating info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `rating` property.

Document Require Rules info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `rules` property.

Document Require Specificationversion info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `specificationVersion` property.

Document Require Tag info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `tags` property.

Document Require Type info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `type` property.

Document Require URL info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `url` property.

Document Require Visibility info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `visibility` property.

Document Require Workflow info experience: governanceexperience: discoverability spec: document

apis-json document should declare a `workflows` property.

Info APIs JSON Specification Version Format info experience: versioningexperience: consistency spec: document

specificationVersion should be a major.minor version (e.g. 0.21).

Maintainer Email Format info experience: consistency spec: maintainers

A maintainer email should be a valid email address.

Schema Include API Lifecycle info experience: governanceexperience: versioning spec: apisspec: properties

This property makes sure there is an API lifecycle schema defining all of the stages of a lifecycle and which policies get applied at each stage of the API lifecycle.

Schema Include API Plan info experience: usabilityexperience: documentation spec: apisspec: properties

This property provides a link to the dedicated plans page that applies to an API, providing information about access tiers, rate limits, and features available for an API as part of a wider API business plan.

Schema Include Authentication Page info experience: securityexperience: documentation spec: apisspec: properties

This property ensures that there is a human readable authentication page available that will provide what type of authentication is used and how it can be applied, as well as any services or tooling that API consumers can use to troubleshoot authentication with APIs.

Schema Include Blog info experience: documentationexperience: discoverability spec: apisspec: properties

This property ensures that an API has a reference to a blog where anyone can find updates and other stories that will help keep API consumers and other stakeholders up to speed on what is happening with an API, and the larger operations.

Schema Include Blog Feed info experience: documentationexperience: discoverability spec: apisspec: properties

This property ensures that blogs in support of APIs have an Atom or RSS feed of posts, allowing for the syndication of updates and information around individual APIs and the operations around them.

Schema Include Business Validator info experience: governance spec: apisspec: properties

This property ensures that there is a link to the validator for the APIs.

Schema Include Change Log info experience: versioningexperience: documentation spec: apisspec: properties

This property ensures that than an individual API or API operations possesses a change log that catalogs all the changes that have occurred in a recent time frame, with historical and version information available if possible.

Schema Include Deprecation Policy info experience: versioningexperience: governance spec: apisspec: properties topic: deprecation

This property ensures that an API has a deprecation policy shared as part of the contract, communicating what the lifespan of APIs are, each individual version, as well as communication around the deprecation of APIs.

Schema Include Developer Portal info experience: discoverabilityexperience: usability spec: apisspec: properties

This property ensures there a developer portal associated with an API and that you can find a landing page for the API, documentation, SDKs, and other resources.

Schema Include Discussion Forum info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that there is a link to a discussion forum, providing a way for consumers and producers to engage and support either other throughout the lifecycle.

Schema Include Documentation info experience: documentationexperience: usability spec: apisspec: properties

This property ensures that there is documentation published for an API, and API consumers will have a set of human-readable instructions for onboarding and integrating with HTTP APIs in their applications.

Schema Include Examples info experience: documentationexperience: usability spec: apisspec: properties

This property ensures that an API has a reference to a examples for individual APIs or as part of common properties, providing examples and synthentic data that can be used for APIs.

Schema Include Feedback Email info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that there is an email available for API consumers to provide feedback.

Schema Include Feedback Issues URL info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures there is a URL to Git issues specifically for providing feedback.

Schema Include Gateway Reference info experience: governanceexperience: discoverability spec: apisspec: properties

This property ensures that there is a reference to the gateway for an API, referencing where you can manage the configuration for each API.

Schema Include Getting Started info experience: documentationexperience: usability spec: apisspec: properties

This property ensures that there is a getting started link available, providing a reference for API consumers to get started with an API is as few steps as possible.

Schema Include Github Action info experience: governanceexperience: reliability spec: apisspec: properties

This property ensures that a GitHub Actions CI/CD pipeline is available for an API, providing a link to the pipeline YAML artifact, which can be used to automate and govern the API as part of the build process.

Schema Include Github Organization info experience: discoverabilityexperience: documentation spec: apisspec: properties

This property ensures that an API is associated with GitHub organization, providing the URL to where you can engage with the operations surrounding an API.

Schema Include Github Repository info experience: discoverabilityexperience: documentation spec: apisspec: properties

This property ensures that an API possess a reference to a dedicated GitHub repository that is used to manage the Open, but also possible server and client code.

Schema Include Governance Policies info experience: governance spec: apisspec: properties

This property ensures there is a governance policies reference as part of an API contract, usually a common property pointing to a centralized set of policies that get applied.

Schema Include Insomnia Collection info experience: usabilityexperience: documentation spec: apisspec: properties

This property defines an Insomnia collection available for each API, providing executable artifacts that can be used in the Insomnia client for making calls, and executing automation workflows.

Schema Include Interface License info experience: governanceexperience: documentation spec: apisspec: properties

This property ensures that an API Commons interface license exists for an API, providing a machine-readable reference for an API, as well as data, backend, and front-end code.

Schema Include Mock Server info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that an API has a reference to a mock servers for individual APIs or as part of common properties, providing mocked deployments of an API that can be used for making test API calls.

Schema Include Openapi Definition info experience: documentationexperience: discoverability spec: apisspec: properties

This property ensures that there is an OpenAPI present for an API, providing the technical contract that describes the surface area of an API.

Schema Include Openapi Governance Rules info experience: governance spec: apisspec: properties

This property ensures that an OpenAPI has support governance rules, that can be applied during design time via editors, development time via IDE, and run-time via CI/CD pipelines.

Schema Include Openapi Validator info experience: governance spec: apisspec: properties

This property ensures that there is a link to the validator for the OpenAPI technical contract, allowing anyone to see the details of governance being applied.

Schema Include Operational Rules info experience: governance spec: apisspec: properties

This property ensures that an API has operational level rules for APIs.

Schema Include Performance Testing info experience: reliabilityexperience: documentation spec: apisspec: properties

This property ensures that an API has performance testing in place, providing a URL to the performance testing, dashboard, or other resource.

Schema Include Postman Collection info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that an API has at least one Postman Collection associated with it, providing automation, tests, and other executable derivatives of an APIs OpenAPI.

Schema Include Postman Public Workspace info experience: usabilityexperience: discoverability spec: apisspec: properties

This property ensures that an API is associated with a Postman Workspace, providing a single location that API producers and/or API consumers can engage around an API.

Schema Include Pricing info experience: usabilityexperience: documentation spec: apisspec: properties

This property provides a link to a pricing page that applies to an API, providing a breakdown of the costs associated with using an API.

Schema Include Privacy Policy info experience: governanceexperience: documentation spec: apisspec: properties

This property provides a link to the privacy policy for an API, providing the legal details of how privacy is approached for each API.

Schema Include Production Environment info experience: usabilityexperience: reliability spec: apisspec: properties

This property ensures that there is a production environment available for an API, providing base URL, tokens, keys, and other key / value pairs that are needed to integrate with an API.

Schema Include Questions Issues URL info experience: usabilityexperience: documentation spec: apisspec: properties

This property ensures that an API has a dedicated link to Git issues for asking questions.

Schema Include Rate Limit Reference info experience: reliabilityexperience: documentationexperience: performance spec: apisspec: properties topic: rate-limiting

This property ensures there is an API rate limits reference associated with API, ensuring the rate limits applied to an API are clearly communicated.

Schema Include Staging Environment info experience: usabilityexperience: reliability spec: apisspec: properties

This property ensures that there is a staging environment available for an API, providing base URL, tokens, keys, and other key / value pairs that are needed to integrate with an API.

Schema Include Version Comparison info experience: versioningexperience: documentation spec: apisspec: properties

This property ensures that an API has the ability to compare two different versions of an API and see what the difference are between them.

Tag APIs JSON Not Empty info experience: discoverability spec: tags

If tags are declared they should not be empty — tags drive discovery in the catalog.

Tag Require Upper Case info experience: namingexperience: consistencyexperience: discoverability spec: tags

Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of every word in a phrase treated the same way.