Versioning should be scoped in README

[TNieminen]

Since the template is encouraging API versioning, a guideline for API versioning should be outlined. One good example of this can be found in Atlassian docs:

Version Control for APIs

https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/#version-control-for-apis

APIs must be subject to version control. The version number of an API appears in its URI. For example, use this URI structure to request version 1 of the 'upm' API:

http://host:port/context/rest/upm/1/...

When an API has multiple versions, we recommend:

Two versions should be supported at the same time. If two or more versions are available, applications may provide a shortcut to the latest version using the latest key-word. For example, if versions 1 and 2 of the 'upm' API are available, the following two URIs would point to the same resources:

host:port/context/rest/upm/latest/ http:host:port/context/rest/upm/2/

When to Change the Version A version number indicates a certain level of backwards-compatibility the client can expect, and as such, extra care should be taken to maintain this trust. The following lists which types of changes necessitate a new version and which don't:

Changes That Don't Require a New Version

New resources New HTTP methods on existing resources New data formats New attributes or elements on existing data types

Change That Require a New Version

Removed or renamed URIs Different data returned for same URI Removal of support for HTTP methods on existing URIs

[HoukasaurusRex]

Yeah I can include that in the README for sure, but what do you think of the strategy? Should the versions be nested in folders this way or should provider/controller files be named provide-something.v1.js instead?

[HoukasaurusRex]

The question of versioning might be bigger as well, like do we want to provide long term support to multiple API versions? This server will actually default a versionless URI to whatever version specified, so we might want to consider as we solidify our resource standards to at least internally defaulting to versionless, while only using versions for when we want to prevent a breaking change on our own front end. That way we can also deprecate versions as we need.

[TNieminen]

Yeah I can include that in the README for sure, but what do you think of the strategy? Should the versions be nested in folders this way or should provider/controller files be named provide-something.v1.js instead?

I personally like file structure over dot notation because it keeps folders more easily readable, but that is just a personal preference.

vs

[TNieminen]

This server will actually default a versionless URI to whatever version specified, so we might want to consider as we solidify our resource standards to at least internally defaulting to versionless

Do you mean that the LTS API version would be running at versionless? so v1, v2, v3 are some new features, but if the latest feature is v4, it would also be available without a version basically working rather similarly to the atlassians /latest/?

As for deprecating APIs, I think it would be good to have a clear deadline for the front-end for deprecation so they know by what time they should by latest react. We could for instance seek to support (like atlassian) two versions at a given time, and if we for instance have now added a v3, we would set a deprecation message to all v1 APIs (hopefully with a setup where we can change this in only one place) that by one month from now this API will be deprecated. We could have for instance a standard format in the response body:

{ deprecatesBy:new Date() }

and then on the frontend we could go

if(res.body.deprecatesBy){ console.warn(API ${req.url} is set to be deprecated by ${res.body.deprecatesBy}) }

[HoukasaurusRex]

Yeah sure, we can include that in the JSend spec to deprecate APIs. The important thing here is to make sure we agree that API versions shouldn't be supported long-term since we don't have the manpower to maintain them. I think versioning makes more sense when you serve thousands of different clients who rely on stable APIs on their business end. Without that, it should be slightly discouraged.