Public API: Document versioning policies of the API and change implications

[tahini]

The current API is 1.0. As long as we don't change or delete anything, we don't need to bump the major. But what about the minor? Any addition to the API should imply a minor version update.

To specify in which version a specific field or endpoint was added, copilot suggests:

• either to mention in the description tag of the element

paths:
  /api/v1/newEndpoint:
    get:
      summary: New endpoint
      description: |
        This endpoint was added in version 1.2.0.
        Retrieves new data.
   ...

• Use custom extensions starting with x-

paths:
  /api/v1/newEndpoint:
    get:
      summary: New endpoint
      description: Retrieves new data.
      x-added-in-version: '1.2.0'
  ...

The server should also have a /version or /versions endpoint to advertise which API versions it supports. Copilot agrees and suggests the following details:

• Endpoint Path: Use a clear path like /api/versions.
• Response Format: Return a structured JSON response with version details.
• Version Details: Include version number, release date, status, and description.

with a response like this

[
  {
    "version": "1.0",
    "releaseDate": "2022-01-01",
    "status": "active",
    "description": "Initial release with basic functionality."
  },
  {
    "version": "1.1",
    "releaseDate": "2022-06-01",
    "status": "active",
    "description": "Added new endpoints for paths and nodes."
  },
  {
    "version": "1.2",
    "releaseDate": "2023-01-01",
    "status": "active",
    "description": "Introduced scenarios endpoint and other improvements."
  }
]