API Versioning and Reporting

Summary

API should provide a reason version and list/matrix of capabilities for a given instance of CDA

Opinions

Opinion 1 Calendar versioning

@MikeNeilson

Summary: Calendar versioning is easier to support and automate with this API

As the one whose has been making the “official” releases Semantic Version versioning has basically been useless. We have been making so many feature additions that if I was doing it right we’d never have a minor version change between releases. It’s also caused me to, I think, release too slowly.

While we can automate SemVer it is an additional step.

With Calendar Versioning automation tools can just pick the current date when appropriately triggered, perhaps by merged into a particular branch.

@adamkorynta

Summary: Calendar versioning more directly aligns with consumers needs

Deprecation, desupport, and removal notices usually involve timelines rather than predicting x number of major/minor releases into the future.

Given the endpoints themselves are already versioned, following semver becomes obtuse with only a real use-case of structural changes such as supported JDK changes, etc.

Opinion 2 Users

Summary: It has been asked more than once that a version be provided

Having a version allows client to better respond to what’s available instead of failing in obtuse ways.

Decision Status

accepted

  1. Provide endpoint to retrieve current API version.

  2. Likely include capability list or matrix.

References