An interesting question was brought up in email.

The REST API versioning is a single integer value that is set in the Roundup code.
However the actual data returned (shape/fields in the data payload, data types for
fields in the payload) is a function of the schema definition not the Roundup code
version.

Changes to the schema often require changes to the html to match the schema. Similarly
changes to the schema will require changes to clients of the API. However there is
no mechanism for the tracker to modify the API version to indicate a mismatch to the client.

There is no need for this right now as there don't seem to be a lot of REST clients that
are not under the control of the tracker admin. So the rest client can be updated similar
to the html files.

Also changes that:

  add fields to the data payload

shouldn't need an API version change. These non-breaking changes should just be
ignored by the client. But breaking changes that:

  replace/rename existing properties

  remove existing properties

  change the type (string -> integer) of an existing property. (Also changing the form
    from single value (link) to list (multilink) falls into this category. Note Roundup
    doesn't support this type of mutation directly, but it can be done with a dump/restore.)

should have an API change.

Also how to represent this. I guess some form of:

   roundup_api.schema_primary.schema_secondary

where each element is an integer. A change to roundup_api or schema_primary means the
rest API has a breaking change.

A schema_secondary increment represents a minor non-breaking change (e.g. adding a
property to any object in the schema).

Implement:

A mechanism to set the default (which is current schema) schema_primary and
schema_secondary values. (If not set, use 1 and 1.) Return this version of the api
if client doesn't supply version. Method/function to set these should be defined for
use in schema.py to keep setting version with the definition.

Code to return three value API version in /rest/ endpoint.

Mechanism to allow tracker to respond with output compatible with an earlier
version of an API. Some sort of mutation method for output from the core code
might work. Call mutation if the schema_primary is present and does not match.
roundup_api difference should be handled by core code.

This could take a full requested api version (including schema_secondary if present)
and object to be returned before it is turned into json. It can handle:

  renames/replacement of fields - remap to older field name
  removal - add removed property and provide dummy value
  type changes (int->string) - change type in object (how to handle link<->multilink
    might not be possible)
   
The mutation should be able to return http status 406 to the client:

   The 406 (Not Acceptable) status code indicates that the target
   resource does not have a current representation that would be
   acceptable to the user agent, according to the proactive negotiation
   header fields received in the request (Section 5.3), and the server
   is unwilling to supply a default representation.

indicating that it can't return the data in the required form.

Method used to manage api version by implementing only the newest version
and modifying the returned object to earlier API versions.

https://dev.to/monite/api-versioning-at-monite-3ba3

Taken from stripe's api management ideas.