5

How to mark APIs as unused in OpenAPI 3.x, when the library is not ready for consumption by other microservices which intend to use the API

Note: Right now, we build a lot of API(s) and they are in various stages of development. Is there a way to annotate this, so that other developers know that there are API(s) which are still work in progress

Rpj
  • 5,348
  • 16
  • 62
  • 122

1 Answers1

3

OpenAPI specification till 3.1.0 doesn't define a way to describe the maturity level of the API.

There was a proposal about adding /info/lifecycle to describe lifecycle and maturity information. But it doesn't seem to get conclusion.

You can define OpenAPI extension to store the information. Just like the /info/x-maturity in Smart API Specification:

x-maturity enum : Maturity of the API. Values to use: development, staging, production.

Another way is to represent your API maturity/readiness in the API version. The semantic versioning allows you to append additional labels for pre-release in the version. For example, any developer should know an API with version 1.0.0-alpha.1 or 1.0.0-dev.1 is still work in progress and not ready for use.

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. ...... A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.

aleung
  • 9,848
  • 3
  • 55
  • 69