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
```json
{
"capabilities": {
"openpodcastapi::betav1",
"openpodcastapi::core",
"openpodcastapi::corev2",
"openpodcastapi::optional": [
"coversync",
"queuesync"
],
"openpodcastapi::optional::v2": [
"coversync",
"queuesync"
],
"othergroup::socialsharing"
}
}
```
```json
{
"capabilities": {
"openpodcastapi::core",
"openpodcastapi::corev2",
"openpodcastapi::optional": [
"coversyncv1",
"queuesyncv1"
],
"openpodcastapi::optional": [
"coversyncv2",
"queuesyncv2"
]
}
}
```
Here is a JMAP auth response with capabilities:
```json
{
"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`