Versioning

[kinlane]

This is the thread to discuss the versioning plan for the API. The starting suggestion is to use the current v1.0 and v1.1, with keeping in alignment with semantic versioning used by major providers like Google - http://apievangelist.com/2017/03/09/guidance-on-versioning-your-api-from-google/.

The current plan is to place the version in the url, right after the baseurl for the API. It's open for discussion for changing strategy with the current release. After that we will probably lock in.

[kinlane]

Submitted @klambacher in #41: by The recommendation to nest versioning in a specific place in the routing path is a more practical recommendation I think. This allows those with the means to simultaneously support multiple versions, explicitness in transitions between versions, and hopefully will allow for gentle transitions. In this case, I think the version number should be a standard part of the route path so that this is expected and predicable.

[NeilMcKLogic]

Agreed. Do you also address what HSDS version is requested? As that spec progresses it is conceivable there will be breaking changes so API requests should include which version of HSDS one wants. Maybe that can go in the header, rather than complicating the routes?

[kinlane]

TimG:

I believe a /latest/ path would point to the latest version of an API.

I would think this should be avoided, as the point of a versioned API path is to avoid applications accidentally being hit by breaking changes.

Given using semantic versioning, a 1.1 of an api should be backwards compatible, I would suggest that versioning in the URL only needs to accommodate the MAJOR version:

I.e. /v1/ will point to the latest MINOR release from the 1.x series so that a change of path is only needed for a backwards incompatible /v2/ release

[kinlane]

The guidance for versioning will be major release in the base path, as follows.

servers:
- url: "{{ hsda_base_url }}" 
  variables:
    basePath:
      default: "/v2"