Make the versioning mechanism clearer

[doga]

Many Qworum APIs will use a CDN, so the versioning mechanism should support client-side caching. I see two ways for Qworum APIs to implement this.

𝌣 Always call a specific API version

The version strings can be anything, but each version must have different version string. Version string examples:

• v1, v2 ...
• 1 ...
• v1.0.0 ...

The version string must be updated even for patch releases.

Advantage of this approach: Easy to implement.

Disadvantage of this approach: Having to serve all API versions grows the code base; pruning breaks applications.

𝌣 The API can choose the most suitable version for the caller

Using the semantic versioning notation for the version string recommended.

The API call can be for:

• a major version, (v1)
• a minor version (v1.2)
• a specific version (v1.2.3)

The major version redirects to a specific version. This specific version can change over time:

• a call to /v1/home/ can redirect to /v1.0.0/home/, /v1.1.9/home/ etc

The caller of the API (= Qworum class) must know the class version for each Qworum object so that endpoint calls are always for the same class version for a given Qworum object. For this, Qworum objects can store their version string in a local JSON data container:

// What happens in the called endpoint
await Qworum.setData(['@', 'class version'], Json('1.2.3'));

// What happens in the caller
const version = await Qworum.getData([
    '@', 'object', // '@' would be omitted if the called object is method-local rather than object-local.
    'class version'
]); 

Advantages of this approach:

• The code base can be pruned, even down to one release per major version.
• Checking if a Qworum object exists is easy; check if its 'class version' property exists. Note that this approach applies to the other solution as well.

Disadvantages of this approach:

• Harder to implement.
• Slows down the application.
• If an API version is pruned while an application is using it, the application must be restarted.