New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Versioning #8

Open
kinlane opened this Issue Apr 14, 2017 · 3 comments

Comments

Projects
None yet
2 participants
@kinlane
Contributor

kinlane commented Apr 14, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jul 14, 2017

Contributor

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.

Contributor

kinlane commented Jul 14, 2017

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.

@NeilMcKechnie

This comment has been minimized.

Show comment
Hide comment
@NeilMcKechnie

NeilMcKechnie Aug 10, 2017

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?

NeilMcKechnie commented Aug 10, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Aug 31, 2017

Contributor

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

Contributor

kinlane commented Aug 31, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment