diff --git a/README.md b/README.md index 16fc26de6b..71922f390a 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,7 @@ Note that the webapp library, ARM templates and Web.Zip package are for testing - [Conformance Statement](docs/resources/conformance-statement.md) - [Health Check API](docs/resources/health-check-api.md) - [Performance Guidance](docs/resources/performance-guidance.md) +- [Api Versions](docs/api-versioning.md) ## Development @@ -73,6 +74,7 @@ Note that the webapp library, ARM templates and Web.Zip package are for testing - [Tests](docs/development/tests.md) - [Identity Server Authentication](docs/development/identity-server-authentication.md) - [Roles](docs/development/roles.md) +- [API Versioning (developer)](docs/development/api-versioning-developers.md) ## Contributing diff --git a/docs/api-versioning.md b/docs/api-versioning.md new file mode 100644 index 0000000000..ed185c15d6 --- /dev/null +++ b/docs/api-versioning.md @@ -0,0 +1,47 @@ +# API Versioning for DICOM Server + +This guide gives an overview of the API version policies for DICOM Server. + +All versions of the DICOM APIs will always conform to the DICOMweb™ Standard specifications, but versions may expose different APIs based on our [conformance statment](https://github.com/microsoft/dicom-server/blob/main/docs/resources/conformance-statement.md). + +## Supported Versions + +A list of supported versions and details of what is supported can be found in the swagger documentation at swagger/v{version}/swagger.json. + +### Prerelease versions + +An API version with the label "prerelease" indicates that the version is not ready for production, and should only be used in testing environments. These endpoints may experience breaking changes without notice. + +### Breaking changes + +We will increment the API version number for any breaking changes to the API. + +Breaking changes: +1. Renaming or removing endpoints +2. Removing parameters or adding mandatory parameters +3. Changing status code +4. Deleting property in response or altering response type at all (but okay to add properties to the response) +5. Changing the type of a property +6. Behavior of an API changes (changes in buisness logic, used to do foo, now does bar) + +Non-breaking changes (API is not incremented): +1. Addition of properties that are nullable or have a default value +2. Addition of properties to a response model +3. Changing the order of properties + +## Headers + +`ReportApiVersions` is turned on, which means we will return the headers `api-supported-versions` and `api-deprecated-versions` when appropriate. + +- `api-supported-versions` will list which versions are supported for the requested API. It is only returned when calling an endpoint annotated with `[ApiVersion("")]`. + +- `api-deprecated-versions` will list which versions have been deprecated for the requested API. It is only returned when calling an endpoint annotated with `[ApiVersion("", Deprecated = true)]`. + +Example: + +``` +[ApiVersion("1.0")] +[ApiVersion("1.0-prerelease", Deprecated = true)] +``` + +![Response headers](images/api-headers-example.PNG) \ No newline at end of file diff --git a/docs/development/api-versioning-developers.md b/docs/development/api-versioning-developers.md new file mode 100644 index 0000000000..c5eec860c7 --- /dev/null +++ b/docs/development/api-versioning-developers.md @@ -0,0 +1,67 @@ +# API Versioning for DICOM Server - Developer Guide + +This guide gives an overview of the API versioning of the REST endpoints for DICOM Server. + +## Routes + +API Version number are set within the route. Example: +`/v1.0-prerelease/studies` + +To add a route, use the `[VersionedRoute]` attribute to automatically add the version number to the route. Example: +```C# +[HttpPost] +[VersionedRoute("studies")] +public async Task PostAsync(string studyInstanceUid = null) +``` + +## Incrementing the version + +We will only increment the major version of the API, and leave the minor version at 0. Ex: 1.0, 2.0, 3.0, etc. + +### Breaking change +The major version must be incremented if a breaking change is introduced. + +List of things we will consider to be a breaking change +1. Renaming or removing endpoints +1. Removing parameters or adding mandatory parameters +1. Changing status code +1. Deleting property in response or altering response type at all (but okay to add properties to the response) +1. Changing the type of a property +1. Behavior of an API changes (changes in buisness logic, used to do foo, now does bar) + +More info on breaking changes from the [REST guidelines](https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#123-definition-of-a-breaking-change) + +Additive changes are not considered breaking changes. For example, adding a response field or adding a new route. + +Bug fixes are not considered breaking changes. + +### Prerelease versions + +Adding a version with the status "prerelease" is a good idea if you have breaking changes to add that are still prone to change, or are not production ready. +Prerelease versions may experience breaking changes and are not recommended for customers to use in production environments. + +`[ApiVersion("x.0-prerelease")]` + +or + +`ApiVersion prereleaseVersion = new ApiVersion(x, 0, "prerelease");` + +### How to increment the version + +1. Add a new controller to hold the endpoints for the new version, and annotate with `[ApiVersion("")]`. All existing endpoints must get the new version. +2. Add the new version number to `test/Microsoft.Health.Dicom.Web.Tests.E2E/Rest/VersionAPIData.cs` to test the new endpoints. +3. Test to verify the breaking changes were not added to the previous version(s). + +## Deprecation + +We can deprecate old versions by marking the version as deprecated as follows: +```c# +[ApiVersion("2.0")] +[ApiVersion("1.0", Deprecated = true)] +``` + +TBD: When to deprecate and when to retire old versions + +## Communicating changes to customers + +TBD: if process is needed for developers to document their changes to communicate to customers \ No newline at end of file diff --git a/docs/images/api-headers-example.PNG b/docs/images/api-headers-example.PNG new file mode 100644 index 0000000000..63a30ecf3f Binary files /dev/null and b/docs/images/api-headers-example.PNG differ