From 54f3afe1b6538f06afbcca6bd4b91f536cd516d3 Mon Sep 17 00:00:00 2001
From: Joas Schilling <coding@schilljs.com>
Date: Thu, 9 Jun 2022 12:55:39 +0200
Subject: [PATCH] Document user preferences API

Signed-off-by: Joas Schilling <coding@schilljs.com>
---
 developer_manual/client_apis/OCS/index.rst    |  1 +
 .../OCS/ocs-user-preferences-api.rst          | 77 +++++++++++++++++++
 developer_manual/client_apis/index.rst        |  4 +-
 3 files changed, 79 insertions(+), 3 deletions(-)
 create mode 100644 developer_manual/client_apis/OCS/ocs-user-preferences-api.rst

diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst
index 1e356151a..5fe99f6f9 100644
--- a/developer_manual/client_apis/OCS/index.rst
+++ b/developer_manual/client_apis/OCS/index.rst
@@ -10,3 +10,4 @@ OCS API
    ocs-share-api
    ocs-sharee-api
    ocs-status-api
+   ocs-user-preferences-api
diff --git a/developer_manual/client_apis/OCS/ocs-user-preferences-api.rst b/developer_manual/client_apis/OCS/ocs-user-preferences-api.rst
new file mode 100644
index 000000000..6157e577a
--- /dev/null
+++ b/developer_manual/client_apis/OCS/ocs-user-preferences-api.rst
@@ -0,0 +1,77 @@
+========================
+OCS user preferences API
+========================
+
+The OCS user preferences API allows you to set and delete preferences from outside over pre-defined OCS calls.
+
+The base URL for all calls to the share API is: *<nextcloud_base_url>/ocs/v2.php/apps/provisioning_api/api/v1/config/users/*
+
+All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
+
+Setting a preference
+--------------------
+
+* Method: ``POST``
+* Endpoint: ``/{appId}/{configKey}``
+* Data:
+
++-------------+--------+------------------------------------+
+| field       | type   | Description                        |
++-------------+--------+------------------------------------+
+| configValue | string | The value to set the preference to |
++-------------+--------+------------------------------------+
+
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If the preference is not allowed to be modified or the given value is invalid
+        + ``401 Unauthorized`` If the request is not done with a user
+
+Setting multiple preference
+---------------------------
+
+* Method: ``POST``
+* Endpoint: ``/{appId}``
+* Data:
+
++--------+-------+--------------------------------------------------------------------------------+
+| field  | type  | Description                                                                    |
++--------+-------+--------------------------------------------------------------------------------+
+| config | array | Key value pairs of config sets with configKey (string) => configValue (string) |
++--------+-------+--------------------------------------------------------------------------------+
+
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If any preference is not allowed to be modified or the value is invalid. No preference will be modified.
+        + ``401 Unauthorized`` If the request is not done with a user
+
+Deleting a preference
+---------------------
+
+* Method: ``DELETE``
+* Endpoint: ``/{appId}/{configKey}``
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If the preference is not allowed to be deleted
+        + ``401 Unauthorized`` If the request is not done with a user
+
+Deleting multiple preference
+----------------------------
+
+* Method: ``DELETE``
+* Endpoint: ``/{appId}``
+* Data:
+
++------------+-------+---------------------------------------+
+| field      | type  | Description                           |
++------------+-------+---------------------------------------+
+| configKeys | array | List of configKeys (string) to delete |
++------------+-------+---------------------------------------+
+
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If any preference is not allowed to be deleted. No preference will be deleted.
+        + ``401 Unauthorized`` If the request is not done with a user
diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst
index 177895b77..f5f6fc0c8 100644
--- a/developer_manual/client_apis/index.rst
+++ b/developer_manual/client_apis/index.rst
@@ -12,7 +12,5 @@ Clients and Client APIs
     OCS/index
     LoginFlow/index
     RemoteWipe/index
-    OCS/ocs-share-api
-    OCS/ocs-sharee-api
     activity-api
-    
+