search

EasyDynamics / oscal-rest

An initial OpenAPI definition of an OSCAL REST API.
Creative Commons Attribution Share Alike 4.0 International
38 stars 13 forks source link

Version Handling #79

Closed brian-comply0 closed 7 months ago

brian-comply0 commented 9 months ago

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 commented 9 months ago

@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:

image

Here's a good summary of different best practices.

cdroblee commented 9 months ago

@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:

image

Here's a good summary of different best practices.

brian-comply0 commented 9 months ago

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-comply0 commented 7 months ago

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

brian-comply0 commented 7 months ago

@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.