Versioning of the API

[korelstar]

Background

Until now, all changes of the API for mobile clients were fully backward compatible. This was realized by ignoring all unknown fields from client resp. server. But someday, we will have to implement a breaking change (e.g. due to #190) and therefore introduce a new major version of the API.

Problem

Currently, clients can't request the supported API versions from the server. I.e., the client can't know which major version is compatible, instead it has to try it out (which is also the case in order to check if the notes app is installed at all). The client also doesn't know which minor version is used by the server, i.e., which fields will be processed by the server - e.g. does the server support setting favorites or categories (this was introduced in a minor version of "v0.2")?

Therefore, I would like to introduce a clearer versioning scheme in the upcoming app release 3.0 based on these considerations about major and minor version. However, I'm not sure, what's the best way?

Possible Solution

Nextcloud provides the capabilities API which may be a good point where to publish the list of supported API versions.

On the other hand, there is the OCS specification (see also developer manual), which supports versioning. However, it looks like there is only one version per service and it doesn't say anything about minor versions. Furthermore, the notes app doesn't use OCS yet - but we can change this!

Any opinions on this? @nextcloud/notes, @LukasReschke (as the author of the OCS specification).

My current plan is to use the capabilities API in order to provide a list of supported API versions, e.g. [1.3, 2.1]. A client that supports API version 1.2 will use the API endpoint under subpath /v1/ and knows that all fields sent by the client will be processed by the server. A client that supports API version 2.4 will use the API endpoint under subpath /v2/ and knows that only those fields will be processed by the server that are defined in revision 2.1. All features belonging to other fields could be deactivated in the client or a warning could be presented to the user.

[jancborchardt]

Whatever happens, the important thing is to inform all the authors of the apps which work with the Notes app. :) That would be @stefan-niedermann of the Android app and @pbek of QOwnNotes at least, probably more.

cc @rullzer @MorrisJobke for API versioning questions – probably you have some valuable insight?

[stefan-niedermann]

Maybe cc @phedlund for the iOS cloud notes app

[korelstar]

Any opinions on this? Is the OCS API still state of the art?

[stefan-niedermann]

No strong opinions. The capabilities seems like a good place and we are using the version info there for the deck app too.

[korelstar]

This will be finally implemented in #474. The capabilities part is done, the only thing missing is the type of the new v1 API. Therefore, I did a short analysis of the advantages of OCS-Controller vs. API-Controller:

advantages OCS

• if the notes app is not installed or not active, an API call responds with "404 Not Found" (current API-Controller responds with "302 Found" and redirect to files app which send "200 OK" -- this is confusing)
• ... ?

disadvantages OCS

• more adaptation efforts required for clients to switch from old v0.2 API to new v1 (with OCS): old data format is now in JSON element "data".
• slightly higher overhead due to doubled headers in the response body
• behavior on errors: on syntax error in app code, response is "200 OK" with empty body; on not caught exception, response is "404 Not Found" with message "Invalid query"; -- both is confusing (current API controller responses in both cases with "500 Internal Server Error" with a full HTML page in the body)

conclusion

I slightly tend to don't use OCS. What do you prefer @stefan-niedermann @phedlund ?
Any other hints from @nextcloud ?

[stefan-niedermann]

I also tend to don't use OCS. Seems like the behavior would change more than i would thought and the advantages are not that big at all.

Maybe we can discuss this again if we have an API v2.0 in the future with (possible) features like sharing notes - in this case OCS seems to make more sense to me.