APIs.json Rules

This page is dedicated to outlining the API governance rules for managing API operations. The Spectral rules format, applicable to any JSON or YAML schema, is used here to identify patterns and anti-patterns relevant to API operations defined by the APIs.json specification.

APIs.json extends the principles of OpenAPI from individual APIs to broader API operations, enabling the business details of API management to be well-defined and governed alongside technical specifications. This approach fosters greater alignment between product and engineering teams, enhancing the overall API lifecycle.

The APIs.json Specification

APIs.json is a machine readable specification that API providers can use to describe their API operations, providing the business details needed to support business between an API producer and consumer.

aid: apis-json
name: Example API
type: Index
description: |-
  This is an example APIs.json file, demonstrating what is possible with the API discovery specification.
image: https://example.com/apis-json-logo.jpg
tags:
  - API
created: '2024-05-22'
modified: '2024-05-22'
url: http://example.com/apis.json
specificationVersion: '0.18'

Metadata for Overall API Contract and Collections

These are the Spectral rules which can be used to lint for the common metadata applied within an APIs.json, helping improve discovery and onboarding with APIs.

id_card APIs.json Name - The name of a collection of APIs should describe their purpose, target audience, and the problems they aim to solve. While individual APIs should have their own specific names, the name in the APIs.json file should provide a higher-level description, emphasizing the overarching business purpose of the APIs.
fingerprint APIs.json Specification AID - Every collection of APIs should have a unique identifier. This unique API identifier, or AID, serves as a human and machine-readable reference for organizing and managing various APIs. Similar to a barcode, a unique identifier helps track APIs, whether you are discovering them or putting them to use.
description APIs.json Description - Every collection of APIs defined in APIs.json should include a one- or two-paragraph description outlining the purpose of the APIs. While individual APIs should have their own descriptions, the collection’s description should focus on the overall business purpose and the domain in which the APIs are intended to be used.
image APIs.json Image - APIs.json contracts are often used to power discover and distribute as part of API catalogs and marketplaces. These are places where having a visual representation matching the purpose of a collection of APIs helps with discovery and onboarding, allowing some APIs to stand out and make a good first impression on consumers.
calendar_month APIs.json Created - The created property in an APIs.json contract might seem like a minor detail, but it serves an important purpose by providing a timestamp that marks the origin of the intent to offer an interface for business purposes. This property offers a straightforward reference to indicate the age and potentially the maturity of a collection of APIs being used in business operations.
calendar_month APIs.json Modified - The modified property in an APIs.json collection indicates the most recent updates made to a group of APIs. While detailed change logs can provide more specifics, an accurate and up-to-date modified timestamp is essential for tracking and managing changes effectively across operations.
text_fields_alt APIs.json Type - The type property in an APIs.json file classifies the business contracts for different types of API collections. It can represent a simple index for a single API, a template or example to showcase possibilities, or classifications such as contract, search, and network to address specific business or discovery purposes.
change_circle APIs.json Version - The specification version of an APIs.json collection indicates which version of the APIs.json specification is being used. This ensures compatibility and allows for the validation of new properties. While property types are the most common additions, new top-level elements are also being introduced. Proper governance ensures that the correct version of the specification is applied.
link APIs.json Url - The top-level URL in an APIs.json file contains a fully qualified link to where the APIs.json file is published. This URL serves as a reference for the API collection and can also be validated. When an APIs.json file includes URLs to various properties, it can be verified against the top-level domain, ensuring the creation of an authoritative APIs.json artifact.
style APIs.json Tags - Each collection of APIs 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 as part of the collection of APIs, highlighting its business value and the domain in which it is applied.
component_exchange APIs.json Common - An APIs.json artifact can include a set of common properties that describe aspects of API operations shared across multiple APIs in a collection. These common properties are typically managed by a centralized platform team, ensuring consistency and reducing the burden on individual teams. This allows API teams to focus on delivering the unique value of their APIs rather than duplicating efforts on shared operational elements.

Metadata for Each Individual API

These are the Spectral rules which can be used to lint for the common metadata applied to each individual API represented within an APIs.json collection.

aid: apis-json
  name: Example API
  type: Index
  description: |-
    This is an example APIs.json file, demonstrating what is possible with the API discovery specification.
  image: https://example.com/apis-json-logo.jpg
  tags:
    - API
  created: '2024-05-22'
  modified: '2024-05-22'
  url: http://example.com/apis.json
  specificationVersion: '0.18'
  apis:
    - aid: apis.json:example-api
      name: Example API
      description: This provides details about a specific API, telling what is possible.
      image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
      humanURL: http://example.com
      baseURL: http://api.example.com
      tags:
        - API
      properties:
        - type: Documentation
          url: https://example.com/documentation
  common:
    - type: Signup
      url: https://example.com/signup
  maintainers:
    - FN: Kin Lane
      X-twitter: apievangelist
      email: [email protected]

api APIs.json APIs - The APIs property in an APIs.json file enables the definition of one or more APIs as part of a larger collection. Each API within this property has its own subset of metadata, allowing it to be uniquely identified and distinguished from the rest of the collection. This individual metadata contributes to the overall value and functionality of the API collection.
fingerprint APIs.json APIs AID Error - 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.
fingerprint APIs.json APIs AID - 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.
id_card APIs.json APIs Name - Each individual API in an APIs.json collection has its own name property, allowing for a clear description of the API. This name might match the API's title in the OpenAPI Info section, but it could also represent the API's business purpose, as displayed in catalogs and search results.
description APIs.json APIs Description - Each API included in an APIs.json file should have a 1-3 paragraph description. This description serves as the first impression for potential consumers and is often displayed in portals, networks, search results, and other discovery channels. A well-crafted description plays a key role in helping API consumers understand and onboard with the API effectively.
image APIs.json Apis Image - Each API defined within an APIs.json file can include a dedicated image, offering a visual representation of the resource or capability it provides. This enhances the API's approachability and visual appeal in portals, documentation, catalogs, and marketplaces, making it more engaging for potential users.
link APIs.json APIs Human URL - The humanURL property for each API defined in an APIs.json contract provides a link for business or technical consumers to learn more about the API. This URL can direct users to a portal, documentation, or ideally, a dedicated landing page designed specifically to onboard consumers with a single API.
link APIs.json Apis Base URL Error - 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.
link APIs.json Apis BaseURL - 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.
contacts APIs.json Apis Contact Error - 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.
contacts APIs.json APIs Contact - 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.
contacts APIs.json Apis Contact Fn Error - 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.
contacts APIs.json Apis Contact Fn - 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.
contact_mail APIs.json Apis Contact Email Error - 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.
contact_mail APIs.json Apis Contact Email - 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.
tune APIs.json APIs Properties - Each individual API included in an APIs.json file can have a properties collection, which contains specific properties relevant to that API. These properties often start with human-readable elements, such as documentation links, and can also include machine-readable properties to enhance functionality and integration.

Essential Properties

Properties can be applied to either individual APIs or be common across multiple APIs, depending on your approach--either way these are the fundamentals when it comes to API operations.

aid: apis-json
    name: Example API
    type: Index
    description: |-
      This is an example APIs.json file, demonstrating what is possible with the API discovery specification.
    image: https://example.com/apis-json-logo.jpg
    tags:
      - API
    created: '2024-05-22'
    modified: '2024-05-22'
    url: http://example.com/apis.json
    specificationVersion: '0.18'
    apis:
      - aid: apis.json:example-api
        name: Example API
        description: This provides details about a specific API, telling what is possible.
        image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
        humanURL: http://example.com
        baseURL: http://api.example.com
        tags:
          - API
        properties:
          - type: Documentation
            url: https://example.com/documentation
    common:
      - type: Signup
        url: https://example.com/signup

APIs.json Apis Properties Portal - 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
APIs.json Apis Properties Getting Started - 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
APIs.json Apis Properties Documentation - 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
APIs.json Apis Properties Authentication - 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
APIs.json Apis Properties OpenAPI - This property ensures that there is an OpenAPI present for an API, providing the technical contract that describes the surface area of an API
APIs.json Apis Properties Plans - 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
APIs.json Apis Properties Rate Limits - This property ensures there is an API rate limits reference associated with API, ensuring the rate limits applied to an API are clearly communicated
APIs.json Apis Properties Signup - 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
APIs.json Apis Properties Versioning - 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
APIs.json Apis Properties Sdk - This property ensures that there is an SDK available for an API, making it easier for developers to integrate an API into their applications
APIs.json Apis Properties Road Map - 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
APIs.json Apis Properties Change Log - 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
APIs.json Apis Properties Status - 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
APIs.json Apis Properties Support Email - This property ensures that an API has email support, providing a valid email address that can be used to get API support
APIs.json Apis Properties Terms Of Service - This property ensures that an API has a reference to a terms of service, covering the legal side of using an API
APIs.json Apis Properties Privacy Policy - This property provides a link to the privacy policy for an API, providing the legal details of how privacy is approached for each API

Additional Properties

Beyond the essentials, there are many additional properties to consider that can be applied to individual APIs, but also shared as common properties across multiple APIs.

aid: apis-json
  name: Example API
  type: Index
  description: |-
    This is an example APIs.json file, demonstrating what is possible with the API discovery specification.
  image: https://example.com/apis-json-logo.jpg
  tags:
    - API
  created: '2024-05-22'
  modified: '2024-05-22'
  url: http://example.com/apis.json
  specificationVersion: '0.18'
  apis:
    - aid: apis.json:example-api
      name: Example API
      description: This provides details about a specific API, telling what is possible.
      image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
      humanURL: http://example.com
      baseURL: http://api.example.com
      tags:
        - API
      properties:
        - type: Documentation
          url: https://example.com/documentation
  common:
    - type: Signup
      url: https://example.com/signup

APIs.json Apis Properties About - 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
APIs.json Apis Properties Blog - 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
APIs.json Apis Properties Forum - 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
APIs.json Apis Properties License - 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
APIs.json Apis Properties Postman Collection - 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
APIs.json Apis Properties Postman Public Workspace - 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
APIs.json Apis Properties Support Support - 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
APIs.json Apis Properties Teams - This property ensures that there is a reference to the team behind an API, providing a reference to business and engineering stakeholders
APIs.json Apis Properties Use Cases - 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
APIs.json Apis Properties Video - This property ensures there is a reference to a video page or channel for an API
APIs.json Apis Properties Performance - This property ensures that an API has performance testing in place, providing a URL to the performance testing, dashboard, or other resource
APIs.json Apis Properties Github Organization - 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
APIs.json Apis Properties Github Repository - 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
APIs.json Apis Properties Environments Production - 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
APIs.json Apis Properties Environments Staging - 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

Maintainers of Collections

The team producing an API and the maintainers of the APIs.json for a collection of APIs may or may not be same thing, with a suite of rules for communicating who is responsible for the APIs.json

aid: apis-json
  name: Example API
  type: Index
  description: |-
    This is an example APIs.json file, demonstrating what is possible with the API discovery specification.
  image: https://example.com/apis-json-logo.jpg
  tags:
    - API
  created: '2024-05-22'
  modified: '2024-05-22'
  url: http://example.com/apis.json
  specificationVersion: '0.18'
  apis:
    - aid: apis.json:example-api
      name: Example API
      description: This provides details about a specific API, telling what is possible.
      image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
      humanURL: http://example.com
      baseURL: http://api.example.com
      tags:
        - API
      properties:
        - type: Documentation
          url: https://example.com/documentation
  common:
    - type: Signup
      url: https://example.com/signup
  maintainers:
    - FN: Kin Lane
      X-twitter: apievangelist
      email: [email protected]

APIs.json Maintainers Email - The maintainers email is to provide a quick way to contact the maintainer of an APIs
APIs.json Maintainers Fn - The purpose of the FN is to specify the formatted text corresponding to the contact name in the vCard for an APIs
APIs.json Maintainers - The maintainers property is for identifying the entity who is maintaining an APIs

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC