improve documentation on API versions

1 files changed, 35 insertions, 17 deletions

diff --git a/docs/api/README.md b/docs/api/README.md
index 021e1573..606c6d29 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -15,7 +15,7 @@ The endpoint specification for a specific version can be found in separate files
 |  **0.2**    | since Notes 1.0 (2015)         | *(deprecated)* |
 
 
-## Versions and Capabilites
+## Versioning policy
 
 While the notes app evolves and receives new features, it may be required to adopt the API.
 As far as possible, we try to make these changes backward compatible.
@@ -26,13 +26,32 @@ We distinguish major and minor versions:
 - a major version comes with changes that are incompatible to the previous version and therefore would break old clients. Major versions come with a new base URL path.
 - a minor version has changes that are realized compatible to the previous version. Old clients can still use the current API endpoint, but they need adoption in order to use new features.
 
+### Compability between minor versions
+
+Minor versions of the same major version use the same API endpoint (path). Therefore, they must be compatible.
+
+In order to realize forward compatibility between minor versions, clients must follow some general rules regarding the API:
+
+- when processing the JSON response, unknown fields must be ignored (e.g. if API version 1.0 does not define the note's attribute "tags", a client must ignore such an unkown field in order to be compatible with a possible future version (e.g. 1.4) which defines such a field)
+- when processing the HTTP response code, a client must be able to handle newly introduced error codes (e.g. if API 1.0 does not explicitly define response code 405, the client must handle it at least like 400; same with a 5xx code).
+
+In order to realize backwards compatibility between minor versions, a client must follow the following rules:
+
+- when sending a request which uses a feature that wasn't available from beginning of the used major version, the client has to cope with the situation that the server ignores parts of the request
+- when processing the JSON response, the server may ommit fields that where not available from beginning of the used major version
+
+If a client requires a certain feature, it should check the list of supported API version from server (see *Capabilities*).
+
+
+### Capabilites
+
 From Notes app version 3.3, supported API versions can be queried using the [Nextcloud Capabilities API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html#capabilities-api).
 
 A request like
 
 	curl -u user:password -X GET -H "OCS-APIRequest: true" -H "Accept: application/json" https://yournextcloud.com/ocs/v2.php/cloud/capabilities 
 
-will return the following result (irrelevant attributes are omitted):
+will return the following result (in this example, irrelevant attributes are omitted and formatting was introduced):
 
 ```json
 {
@@ -40,7 +59,8 @@ will return the following result (irrelevant attributes are omitted):
     "data": {
       "capabilities": {
         "notes": {
-          "api_version": [ "0.2", "1.0" ]
+          "api_version": [ "0.2", "1.0" ],
+          "version": "3.6.0"
         }
       }
     }
@@ -48,25 +68,23 @@ will return the following result (irrelevant attributes are omitted):
 }
 ```
 
+|  Attribute    | Type            | Description | since app version |
+|:--------------|:----------------|:------------|:------------------|
+| `api_version` | list of strings | list of supported API version; for each supported major API version, the highest supported minor API version is listed, e.g. `[ "0.2", "1.1" ]`  | Notes 3.3 |
+| `version`     | string          | app version, e.g. `"3.6.0"`  | Notes 3.6 |
+
 From Notes app version 3.3, the list of supported API versions is also provided in every response from the Notes API.
 For this, the HTTP header `X-Notes-API-Versions` is used.
 It contains a coma-separated list of versions, e.g., `X-Notes-API-Versions: 0.2, 1.0`.
 
+### Processing API version information
+In order to be compatible to older Notes version, you may want to implement multiple API versions in your client application.
+In this case, you should periodically request OCS capabilities from the server or parse the `X-Notes-API-Versions` HTTP header.
+Your application must then walk through the list of supported API versions and for each version do:
+1. parse the version string (e.g. `1.2`) and gather the major version (here: `1`) as well as the minor version (here: `2`)
+2. check if your client app supports the major version and then check if the minor version is greater or equal than your minimum required minor version for that major version
 
-## Compability between minor versions
-
-In order to realize forward compatibility between minor versions, clients must follow some general rules regarding the API:
-
-- when processing the JSON response, unknown fields must be ignored (e.g. if API version 1.0 does not define the note's attribute "tags", a client must ignore such an unkown field in order to be compatible with a possible future version (e.g. 1.4) which defines such a field)
-- when processing the HTTP response code, a client must be able to handle newly introduced error codes (e.g. if API 1.0 does not explicitly define response code 405, the client must handle it at least like 400; same with a 5xx code).
-
-In order to realize backwards compatibility between minor versions, a client must follow the following rules:
-
-- when sending a request which uses a feature that wasn't available from beginning of the used major version, the client has to cope with the situation that the server ignores parts of the request
-- when processing the JSON response, the server may ommit fields that where not available from beginning of the used major version
-
-If a client requires a certain feature, it should check the `X-Notes-API-Versions` HTTP header of the server response.
-
+Then use the highest API version to which this requirement applies.
 
 ## Authentication