Improve API Versioning

[bauerj]

As it is currently implemented, the API versioning leads to a lot of additional requests from the client to determine a common API version.

See this example for a client that supports API version 3 and a server that supports version 2:

• Client: Request API version 3
• Server: 406 Not Acceptable (without X-API-Version header)
• Client: Request API version 1
• Server: Version 1 response with X-API-Version: 2
• Client: Request API version 2
• Server: Version 2 response with X-API-Version: 2

Those are two unnecessary requests before any data can be shown to the user, which would slow the app down dramatically.

For my use-case it would be better if the server would return the highest available API version if the requested version is not supported. If there are already clients that rely on the 406-handshake behaviour, maybe a special syntax like Accept: application/json, version<3 could be used.

What do you think? Would it be possible to change the behaviour like that?

[jonaswinkler]

I can certainly change the behavior.

The reason for serving version 1 by default is as follows: don't break existing API clients when users update their paperless server.

I don't think I can do version<3 without some major effort.

Does this sound about right?

• Serve v1 if version if not specified (Your opinion?)
• Serve specified version if available
• Serve newest version if specified version is not available

I don't have all that much experience with this stuff, unfortunately :(

[bauerj]

Serve v1 if version if not specified (Your opinion?)

Sure, I do see your point with backwards-compatibility and this seems to be the best way to achieve a consistent behaviour.

Serve newest version if specified version is not available

Yes, that would definitely make the implementation easier for me! Of course then we would need a way to identify the API version used in the response. Something like a X-Actual-API-Version-Used-In-This-Request header - but I'm sure you can come up with a better name 😉

I don't have all that much experience with this stuff, unfortunately :(

Me neither, and I didn't see the problem until actually implementing it client-wise. But no worries, I know APIs where no versioning is used and client compatibility just breaks if they change something. This is definitely better 😄