Version Handling

[brian-ruf-ezd]

As an author of software that calls the OSCAL REST OpenAPI specification, I want to be able to indicate which version of the API spec I am using. This will be important once we get beyond version 1.0.0.

The syntax for identifying the version should be selected, such that it is optional. The implementation may elect to either always require the version or allow it to be omitted. Any implementation that allows the version to be omitted must use the latest available version when no version is specified.

The REST API specification must also provide a mechanism for indicating what version(s) of the specification are supported by a specific implementation.

[cdroblee]

@brian-comply0 definitely good to be thinking about this now.

There are lots of established best practices on how to implement API versioning. I generally prefer URI-based versioning (e.g. https://api.oscal.io/api/v1/catalog) as it's the most explicit and easiest to control, but header and body versioning are also quite common:

Here's a good summary of different best practices.

[cdroblee]

@brian-comply0 definitely good to be thinking about this now.

There are lots of established best practices on how to implement API versioning. I generally prefer URI-based versioning (e.g. https://api.oscal.io/api/v1/catalog) as it's the most explicit and easiest to control, but header and body versioning are also quite common:

Here's a good summary of different best practices.

[brian-ruf-ezd]

Body Versioning sounds like it introduces additional complexity for PUT and POST methods used for transmitting complete OSCAL documents. The OSCAL content could be in XML, JSON or YAML. The endpoints would need to require the content be wrapped as multi-part mime in order to include the syntax version as JSON.

I believe we should set this one aside and consider only URI Versioning and Header Versioning.

[brian-ruf-ezd]

We will use Semantic Versioning for the version number, and URI versioning to specify the version of the API being used.

[brian-ruf-ezd]

@mpemy's OpenAPI generation capability can now insert whatever version number the product owner specifies for a given release, and the supporting documentation cites the use of Semantic Versioning. Closing issue.