On a fediverse server with a versioned client API, what would you expect to happen if an API call is made with a version number higher than what the server supports?

[grishka@mastodon.social]

On a fediverse server with a versioned client API, what would you expect to happen if an API call is made with a version number higher than what the server supports? Should it return an error? Should it take it to mean its highest supported version? Something else?

The API isn't RESTful, the version number is global for all methods (endpoints) and has the format "major.minor".

#Smithereen #ActivityPub #mastodev

[mro@digitalcourage.social]

Hi @grishka,
using highest sounds like best effort and makes most sense to me.

[grishka@mastodon.social]

@mro but what if there are incompatible changes that the app doesn't expect? Like some object having a different format, or some method behaving differently

[nikclayton@mastodon.social]

@grishka Return an error that tells the client it's used an unsupported version.

By definition, the server does not know the semantics of the call the client made, so trying to guess and return something in the hope it's correct takes us out of the realm of engineering and into clairvoyance.

[julian@activitypub.space]

nikclayton@mastodon.social agreed.

It's one thing for a server with a newer API version to be backwards compatible with a request from an older version, but it's impossible to predict the future and handle requests from a newer API client.

Bouncing an error back would be the safest choice.

cc grishka@mastodon.social

[rimu@piefed.social]

Isn't the convention to put the version in the url? e.g. /api/v3/site

In which case a too-high version gives you a 404 error.

[grishka@mastodon.social]

@rimu that's for RESTful APIs, mine isn't that because I dislike the concept. I just take the version as the `v` parameter

[trwnh@mastodon.social]

@grishka @rimu putting the version in the uri is an older convention and not necessarily a REST(ful) thing either. what i've seen is to use content negotiation via an Accept-Version header

basically if you use conneg then 405 Not Acceptable; if you put versions in uris then 404 Not Found; if you take some parameter or payload then i guess maybe 422 Unprocessable Entity?