Add API endpoint containing its current version

[filip-szweda]

Add API endpoint containing its current version

Is your feature request related to a problem? Please describe.
Currently, the API is not versioned.
This means that every change to its JSON structure, data types or data itself comes up as unexpected to the users.
In effect, this breaks applications using the API.

Examples of possibly app-breaking changes to the API:
#2055
#2297

Describe the solution you'd like
Add API endpoint, in a way that it can be accessed at:
https://endoflife.date/api/version
and contains:
{"version":"<version>"}

This would require support of semantic versioning of the API with major releases being JSON structure, data type changes etc. and minor releases being product / product details value updates.

Describe alternatives you've considered
None.

Additional context
This addition would prove endoflife.date more development-friendly.

[captn3m0]

Suggestion: use schema_version instead of version. Version has other meanings in the API, so it might be confusing.

I would like to keep versioning similar to https://ossf.github.io/osv-schema/, which uses the following:

The schema_version field is used to indicate which version of the OSV schema a particular vulnerability was exported with. This can help consumer applications decide how to import the data for their own systems and offer some protection against future breaking changes. The value should be a string matching the OSV Schema version, which follows the SemVer 2.0.0 format, with no leading “v” prefix. If no value is specified, it should be assumed to be 1.0.0, matching version 1.0 of the OSV Schema. Clients can assume that new minor and patch versions of the schema only add new fields, without changing the meaning of old fields, so that a client that knows how to read version 1.2.0 can process data identifying as schema version 1.3.0 by ignoring any unexpected fields.

[usta]

@filip-szweda Our api is still in alpha thus it might be a little unstable , thats the main reason we are trying to implement this one : #2066

[marcwrobel]

FYI the approach taken in #2080 is to version the API using the URL (e.g. /api/v1, /api/v2...) and incrementing the version when there is breaking changes, such as field removal.

This approach makes more sense in our particular context. It allows us to have multiple and concurrent versions of the API to give time to our users to migrate. This would not be possible with a version field because endoflife.date is just a static site.

We could also add a version (or schema_version) field in the response. Maybe it would be useful when an older version of the API is removed and old API URLs are redirected to the new API URLs ? What do you think @filip-szweda, @usta, @captn3m0 ?

[captn3m0]

It would also be helpful when we make minor schema changes (such as field additions).

[adriens]

FYI the approach taken in #2080 is to version the API using the URL (e.g. /api/v1, /api/v2...) and incrementing the version when there is breaking changes, such as field removal.

🙏 👍

[filip-szweda]

I really like your approach in #2080 👍

One thing I'm a bit concerned about are changes to the API that do not add/remove fields like e.g. #2297
Do you think such changes could also increment the API version, perhaps only its minor part (i.e. /api/v1-1, /api/v1-2, /api/v1-3)?