Created on 2023-09-21 15:22 by rouilj, last changed 2023-09-21 15:22 by rouilj.
|msg7833||Author: [hidden] (rouilj)||Date: 2023-09-21 15:22|
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.