Deprecation of pin/unpin accounts and addition of endorse/unendorse don’t have an API version number

[daprice]

The deprecation of pin and unpin, and addition of endorse and unendorse don’t include an API version number on this documentation page, they just say the change was made in Mastodon 4.4.

Are these changes not meant to be tied to an API version (i.e. client devs are expected to use the main Mastodon version number for this), or is it just missing from the docs?

[mjankowski]

Right now in the code these are all just aliases for each other going to same place, running same code.

For clarity here...

• Are you looking for a code change that would include the Deprecated timestamp header in the "pin" ones?
• For an API version bump such that the new "endorse" ones would be under api/v2/*?
• Some introspection about how to find out which one to use, other than knowing the general server version number?
• Something else?

[daprice]

The third thing, specifically an API version number to compare against api_versions[mastodon] in Instance.

I was under the impression that after that was added in 4.3, any future changes would be associated with an API version so clients wouldn’t have to infer everything from the Mastodon version string anymore, but that doesn’t appear to have been the case (or at least isn’t documented) with this or most other features added since then.

[mjankowski]

Got it, thanks.

The api_versions idea was added in August '24 in mastodon/mastodon#31354

The endorse/pin alias/deprecate change was in April '25 - mastodon/mastodon#34421

That introduction did not bump the api version, and I'm not sure if that was an oversight, or intentional and the doc should reflect "whatever the api version happened to be on next release", or something else. It did not come up on the docs PR - #1633

Will leave this open for someone who understands the intention here.

[trwnh]

i would assume an oversight because the api_versions idea seems to be a bit incomplete or inconsistent -- a version bump seems to happen when some significant change is made, and the ability to get account endorsements should have warranted a version bump but didn't. the aliasing of pin/unpin to endorse/unendorse is a bit borderline, but could be viewed as a justification to bump the version as well, although there's generally no reason for clients to use or prefer the aliases over the routes that have been around for a long time and will continue to work on both new and old versions... i can't really imagine a client app that wants to test for support of something they can already do, and i can't imagine client apps switching to the aliased routes either.

re: "the doc should reflect whatever the api version happened to be on next release", i honestly think that versioning the mastodon api by releases instead of by the api_version property makes a lot more sense. if i understand correctly, the main reason api_version was invented at all is because the mastodon team wanted client devs to be able to experiment with new API features before release, i.e. during the pre-release/alpha/beta/rc phase. i think the better thing to do or have done instead is to have something more akin to feature flags, but that's not what we got, so... eh?

[daprice]

As a client dev, I was really hoping api_versions could be a way for different Mastodon-API-compatible server software to programmatically declare which Mastodon API features they support, as opposed to the current situation where every client dev has to maintain a table of feature support versus version numbers for every single Mastodon-API-compatible server software out there (and successfully parse every project’s version numbers!), and must rush out a client update (and users must install it) every time any server software gains support for any feature (or run our own service just so what should be a local-only client can phone home and update its versions-to-features matrix).

Something like feature flags would indeed be much better for that. Really, that would be better for pre-release features as well, because clients that implement a pre-release API can’t know in advance if a future “Mastodon API version" will make a breaking change to a feature introduced in an earlier version.

On the other hand, clients only having to keep up with one monotonically-increasing “API version” number is a lot better than having to accommodate and test every possible permutation of feature flags that a server might declare.

But literally anything would be better than the aforementioned status quo.

[trwnh]

a way for different Mastodon-API-compatible server software to programmatically declare which Mastodon API features they support

unfortunately, api_versions doesn't actually help there because unofficial Mastodon API implementations don't actually align with any version fully. i mean, projects like pleroma will advertise themselves as vaguely compatible with mastodon 2.6 or 2.8 api, but this isn't strictly true because it's more accurately a subset-with-extensions situation.

there's always going to be tension here because, despite being cloned by other software projects, the mastodon api is not a standard. it's a proprietary api developed for mastodon's purposes alone, and there aren't mechanisms in place to support an extended or decentralized ecosystem of API providers. i'd argue that it's possible to take steps toward this, but it would require someone at mastodon to make the decision that mastodon should work toward standardizing its api in some form.

if you wanted to consider similar situations, then i'd say that this is pretty much exactly the same scenario as the Amazon S3 API. other storage service providers wanted compatibility with amazon's api because amazon's api had wider support and an ecosystem of libraries/etc around it. if you take a look at those other providers' documentation, they don't have anything like an api_version and just describe differences instead, or ideally advertise whether each individual operation and/or feature is supported or unsupported. for example:

• cloudflare r2 describes its s3 compatibility here: https://developers.cloudflare.com/r2/api/s3/api/
• backblaze b2 describes differences with s3 here: https://www.backblaze.com/docs/cloud-storage-s3-compatible-api
• wasabi says it aims to be 100% bit-compatible with amazon s3: https://docs.wasabi.com/apidocs/wasabi-api
  • wasabi describes which subset of identity/security token stuff they support: https://docs.wasabi.com/apidocs/iam-and-sts-support

when you consider something like akkoma, which has to maintain documentation on not just mastodon api differences but also the pleroma api methods it inherits and furthermore its own akkoma api extensions... well, it really makes you want better standardization, huh? but it's not entirely clear what that better standardization would look like with respect to namespacing and especially with respect to what a client developer is supposed to be aware of or know ahead-of-time. there are no easy answers to decentralization, but api_versions is not one of them. api_versions is at most just an abstraction layer over mastodon semver to not have to deal with pre-release versions too.

[mjankowski]

Hmm, yeah I thought it was more to reduce the amount of parsing of potentially non standard version strings from forks or totally different software (that implemented some subset of the API) to advertise more consistently what feature-set was present.

Assuming the drop here was either an oversight (which we cant really fix?) or an explicit choice to not bump because the old routes still work ... there's probably not actually a doc change to make now?

(But there would be a code change and doc change if/when the old one was actually fully removed of course)

I could see adding a note on something like #1631 or similar...