API Road Map

An API Road Map is a simple, machine-readable list of the milestones planned for an API—each entry capturing a date, a name, a description, a link, and tags. Where the change log looks backward at what has already shipped, the road map looks forward at what is coming, giving API producers a common way to communicate direction and giving consumers an interoperable place to see what is ahead so they can plan their own applications and integrations. Communicating planned change is a core part of healthy API operations, and the road map is the building block for doing it consistently across the API lifecycle.

API Commons

The API Road Map is an API Commons building block—an open, machine-readable schema that can be produced from any system used to manage APIs, and then made interoperable as part of the API contract. It is indexed as a Common type within its APIs.json index, letting it be discovered, referenced, and reused across the APIs.json ecosystem and surfaced through apis.io.

What's in this repo

• road-map-schema.yml — The JSON Schema that defines a road map item.
• road-map-example.yml — A worked example with a series of road map milestones.
• apis.yml — The APIs.json index for this building block, referencing the schema and example as Common artifacts.

The Schema

The road-map-schema.yml defines each road map item as an object with the following properties:

• date — The target date for the API road map item.
• name — The name for the API road map item.
• image — The image for the API road map item.
• link — The link for the API road map item.
• tags — An array of tags for the API road map item.

Example

The road-map-example.yml file provides a list of road map milestones you can use as a starting point:

- date: 2023-09-01
  name: Milestone One
  description: >-
    Lorem ipsum dolor sit amet, consectetur adipiscing elit...
  image: 'https://s3.amazonaws.com/kinlane-productions2/bw-icons/bw-linkedin.png'
  link: 'https://example.com'
  tags:
    - Tag One
    - Tag Two

How It Fits

The road map is one of a growing set of API Commons building blocks that describe the business and technical realities of API operations in a machine-readable way. It is a natural companion to the change log—the road map for what is planned, the change log for what has shipped—and it cross-links with teams, use cases, plans, guidance, policies, and other building blocks that can stand alone or be composed together within an APIs.json index.

Support

This work is in an early stage of development and is rapidly moving as it is applied across a variety of user interfaces and approaches to API operations and governance. If you would like to contribute, have any questions, or would like to inform the work happening, please submit a GitHub issue on this repository or email kin@apievangelist.com.