2023 08 01

2023-08-01 20:00

Present:

API Versioning

https://github.com/orgs/OpenPodcastAPI/discussions/11

Options:

• Nodeinfo (created by Pleroma): https://docs-develop.pleroma.social/backend/development/API/nodeinfo/
• Specs versioning (to maintain backwards compatibility)

Probably both needed at the same time; even if you're on the same API version your server might not support the same feature set as the client.

--> How do we version our specs? At level of whole specs, or at level of individual calls/endpoints? --> Spec version increases only for core endpoints, or optional ones as well?

Spec version increment with any change (e.g. point-increase in case of changes to/added optional end-points). But the versions in the calls only have the major versions.

• Minor change: only add or deprecate (you should use this version instead, but here is your requested info)
• Major change: drop endpoints/calls, or change the way info is returned. Addition of new core endpoints should also be considered a major change

Note to the future: if a server supports two different major versions, the data coming in through both endpoints should be compatible on database-level. We will have to discuss how this may affect what we are allowed to change in major-version-changes.

Endpoints

• ${base_address}/versions: contains only the version number(s) (x.x.x)
• ${base_address}/v1/capabilities: contains a list of features and their status/related settings

(So on base address, not via .well-known, because the latter is not necessarily present in all servers.)

Versions endpoint

{
    "versions": [
		"v1.1", // translates to /v1/
		"v2.0", // translates to /v2/
	],
}

Capabilities endpoint

Array version:

{
    "capabilities": [
        "queueSync",
        "storeEpisodes"
    ],
    "settings": [
        {
            "name": "queuSync",
            "metadata": {
                "maxQueues": 5
            }
        },
        {
            "name": "subscription_settings_sync",
        }
    ]
}

Array of objects version:

{
    "capabilities": [
        {
            "name": "queue_sync",
            "maxQueues": 5
        },
        {
            "name": "storeepisodes",
            "uploadQuota": 500_000_000
        },
        {
            "name": "subscription_settings_sync",
        }
    ]
}

Nested objects version:

{
    "capabilities": {
        "queue_sync": {
            "maxQueues": 5
        },
        "storeShows": {},
        "storeEpisodes": {
            "uploadQuota": 500
        }
    }
}

For magical-spell-arguments, nested objects are determined better.

--> If a server has disabled a given feature (e.g. I have my instance of PodWire which in principle supports multiple queues but I have disabled this), it can simply be not returned in the capabilities end-point (no need to know why it's not available).

Inspired from example Nodeinfo response:

{
  "version": "string",
  "software": {
    "name": "string",
    "version": "string"
  },
  "protocols": [
    "string"
  ],
  "services": {
    "inbound": [],
    "outbound": []
  },
  "openRegistrations": true,
  "usage": {
    "users": {
      "total": 0,
      "activeHalfyear": 0,
      "activeMonth": 0
    }
  },
  "metadata": {
    "actorId": "string",
    "private": true,
    "shortDescription": "string",
    "longDescription": "string",
    "rules": "string",
    "contactEmail": "string",
    "terms": "string",
    "nodeName": "string",
    "banner": "string",
    "defaultUploadQuota": 0,
    "library": {
      "federationEnabled": true,
      "anonymousCanListen": true,
      "tracks": {
        "total": 0
      },
      "artists": {
        "total": 0
      },
      "albums": {
        "total": 0
      },
      "music": {
        "hours": 0
      }
    },
    "supportedUploadExtensions": [
      "string"
    ],
    "allowList": {
      "enabled": true,
      "domains": [
        "string"
      ]
    },
    "reportTypes": [
      {
        "type": "string",
        "label": "string",
        "anonymous": true
      }
    ],
    "funkwhaleSupportMessageEnabled": true,
    "instanceSupportMessage": "string",
    "endpoints": {
      "knownNodes": "string",
      "channels": "string",
      "libraries": "string"
    },
    "usage": {
      "favorites": {
        "tracks": {
          "total": 0
        }
      },
      "listenings": {
        "total": 0
      },
      "downloads": {
        "total": 0
      }
    }
  }
}

We wouldn't implement full NodeInfo end-point, but could follow a similar approach. E.g. provide all server info together.

Changeability of the returned info:

Packaging

Ideally create a new library for each version. Schema file can be used to crete these through CI. Each (client) project would have only one library (SDK) at a time, with version info for each of the calls, such that a warning is shown if a deprecated call is used and the client software can dynamically determine which calls/parameters should be used/expected.

We should keep track for each call from which version it is available, because client needs to know this info.

tags: project-management meeting-notes OpenPodcastAPI