-
Notifications
You must be signed in to change notification settings - Fork 14
Versioning
Clients, endpoints, database schema, and STAPI data are versioned independently.
Clients for every language are versioned independently from each other, and independently from endpoints, database schema, and STAPI data. Only Java client is maintained as part of this repository. It's best to always use newest version of clients and refer to clients individual documentation.
Some REST endpoints have more than one version. This is because model for the underlying entities had changed, and had to be reflected in the API in a non-breaking maner. This means that newest version is always preferred for client applications, but for now, the older versions of endpoints will work. Endpoints that have only one version should not be considered deprecated, of course.
Java REST client and REST contracts lists endpoints with more than one version. Some endpoints have search V1, but full entity has V2.
UIDs from endpoints versions are compatible, of course, because it's still the same data being served.
SOAP endpoints had only one version, originally created back in 2017, and has since been deprecated in the year 2022, and removed in 2023.
Data is versioned by the month it was gathered, in 2023-03 format. Docker images are versioned in this maner too, as well as database dumps.
Current data version for stapi can be checked here.
Java client since version 0.1.0 has a method to check data version.
The idea of STAPI getting it's data is that a single new instance is feed with data, only once ,via ETL process, and then serves it until it is replaced by a different instance with a freshly loaded data. Therefore only public contracts are guaranteed to not change, but DB schema could change between versions. This is mostly to merge future changes to tables into their original declarations, and to drop old tables without first creating them.
Therefore, if you are in the middle of a development, you pull master branch one day, and see a failed migration, you can either stick to the previous version that worked, or try exporting data to a file, migrating a fresh and empty database with new schema, and importing data back. If that doesn't work, just do your changes, and start using new schema when it is convinient.
So far, breaking changes in schema did not happen, but it's not guaranteed that they will not happen.