2024 11 07

2024-11-07 noon

Versioning & capabilities

Starting point of the discussion: https://github.com/OpenPodcastAPI/api-specs/pull/50#discussion_r1779485473

Key question is whether we need minor versions in the implementation (or 'protocol')

JMAP (replacement for IMAP) When you authenticate, server always replies with 'these are functioalitis/namespaces that I provide'

Our capabilities could be communicated in a similar way, in combination together with versioning. E.g. I support:

• core v1
• core v2

Solves deprication/removal problem. Server perspective: in most cases fine to support multiple versions.

If the server changes, then it should close all open sessions. Then clients have to re-authenticate and learn about the new capabilities.

Having a version- and capabilities endpoint still have a merit.

Versioning

• Protocol: actual implementation by servers & clients
• Specification

How frequently do we think core specifications will change? Each major version should go through collective feedback & testing by developers & users. (e.g. this 'optional' end-point is used by everyone so should be in core).

Core endpoint changes should (aim to) only come in main versions. New or changed features can be 'optional' in

Flow:

• new ideas implemented & tested (technical & user perspective) in beta
• no new changes to the spec, until we cut a new major version

Therefore, from specs perspective, there is only pre- major version and major versions.

Do we still need minor versions if you have the capabilities?

Otherwise, if we have 7 minor versions, developers would need to keep up with these changes. Client devs then would have to implement a lot of if-then logic.

Capabilities

{
  "capabilities": {
     "openpodcastapi::betav1",
     "openpodcastapi::core",
     "openpodcastapi::corev2",
     "openpodcastapi::optional": [
        "coversync",
        "queuesync"
     ],
     "openpodcastapi::optional::v2": [
        "coversync",
        "queuesync"
     ],
     "othergroup::socialsharing"
  }
}

{
  "capabilities": {
     "openpodcastapi::core",
     "openpodcastapi::corev2",
     "openpodcastapi::optional": [
        "coversyncv1",
        "queuesyncv1"
     ],
     "openpodcastapi::optional": [
        "coversyncv2",
        "queuesyncv2"
     ]
  }
}

Here is a JMAP auth response with capabilities:

{
  "capabilities": {
    "urn:ietf:params:jmap:core": { ... }
    "urn:ietf:params:jmap:submission": {},
    "urn:ietf:params:jmap:mail": {}
  },
  "accounts": {
    "u2321401a": {
      "name": "example@example.fm",
      "isReadOnly": false,
      "isArchiveUser": false,
      "isPersonal": true,
      "accountCapabilities": {
        "urn:ietf:params:jmap:submission": {
          "submissionExtensions": {},
          "maxDelayedSend": 44236800
        },
        "urn:ietf:params:jmap:core": {},
        "urn:ietf:params:jmap:mail": {
          "emailQuerySortOptions": [ ... ]
          "maxSizeMailboxName": 490,
          "maxMailboxDepth": null,
          "mayCreateTopLevelMailbox": true,
          "maxMailboxesPerEmail": 1000,
          "maxSizeAttachmentsPerEmail": 50000000
        }
      },
    }
  },
  "primaryAccounts": {
    "urn:ietf:params:jmap:submission": "u2321401a",
    "urn:ietf:params:jmap:core": "u2321401a",
    "urn:ietf:params:jmap:mail": "u2321401a"
  },
  "uploadUrl": "https://api.fastmail.com/jmap/upload/{accountId}/",
  "eventSourceUrl": "https://api.fastmail.com/jmap/event/",
  "downloadUrl": "https://www.fastmailusercontent.com/jmap/download/{accountId}/{blobId}/{name}?type={type}",
  "apiUrl": "https://api.fastmail.com/jmap/api/",
  "username": "example@example.fm"
}

namespace allows us to define capabilities, but also allows anyone external to create their own spec, and servers to commnicate that they support this at that point.

Beta/Testing versions

namespace openpodcastapi::opentional::podcast-cover::beta-v1

Server should still expose this. Clients & servers could support multiple beta versions at a time, or only one at a time.

From specs perspective, we should rethink the capabilities endpoint. Redesign from namespace perspective.

Should be communicated in authentication response. Capabilities endpoint could also be handy. That would enable a flow where user sets up sync, client checks capabilities, and exposes this in a nice way to the user.

tags: project-management meeting-notes OpenPodcastAPI