Merge pull request #5487 from nextcloud/ocs-status-api

Add doc for status api
2026-01-03 02:09:45 +07:00 · 2020-12-07 08:50:03 +01:00
parent 9ece1a07ea b189846039
commit b41891cdcb
1 changed files with 152 additions and 0 deletions
--- a/developer_manual/client_apis/OCS/ocs-status-api.rst
+++ b/developer_manual/client_apis/OCS/ocs-status-api.rst
@@ -0,0 +1,152 @@
+==============
+OCS Status API
+==============
+
+The OCS Status API allows you to access and modify status API 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/user_status/api/v1/user_status*
+
+All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
+
+
+User Status - Status Manipulation
+---------------------------------
+
+Fetch your own status
+^^^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``GET``
+* Endpoint: ``/``
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``404 Not Found`` If the user does not have a status set
+
+Set your own status
+^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``PUT``
+* Endpoint: ``/status``
+* Data:
+
+    field | type | Description | Allowed values
+    ------|------|-------------|---------------|
+    ``statusType`` | string | New status for the authenticated user | ``online``, ``away``, ``dnd``, ``invisible``, ``offline`` | 
+
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If the sent status-type is not valid
+
+Set a custom message (predefined)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``PUT``
+* Endpoint: ``/message/predefined``
+* Data:
+
+    field | type | Description 
+    ------|------|------------
+    ``messageId`` | string | Message-Id of the predefined message
+    ``clearAt``   | int    | Unix Timestamp representing the time to clear the status
+
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If the sent messageId does not exist
+        + ``400 Bad Request`` If the Unix timestamp is in the past
+
+Set a custom message (user-defined)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``, ``supports_emoji`` for ``statusIcon`` support
+* Method: ``PUT``
+* Endpoint: ``/message/custom``
+* Data:
+
+    field | type | Description 
+    ------|------|------------
+    ``statusIcon`` | string/null | The icon picked by the user (must be an emoji, at most one)
+    ``message``    | string      | The custom message picked by the user
+    ``clearAt``    | int         | Unix Timestamp representing the time to clear the status
+
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``400 Bad Request`` If the `statusIcon` is not a an emoji or more than one emoji
+        + ``400 Bad Request`` If the `message` is too long
+        + ``400 Bad Request`` If the Unix timestamp is in the past
+
+Clear message
+^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``DELETE``
+* Endpoint: ``/message``
+* Response:
+    - Status code:
+        + ``200 OK``
+
+User Status - Predefined statuses
+---------------------------------
+
+Base endpoint ics: ``/ocs/v2.php/apps/user_status/api/v1/predefined_statuses``
+
+Fetch the list of predefined statuses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``GET``
+* Endpoint: ``/``
+* Response:
+    - Status code:
+        + ``200 OK``
+
+User Status - Retrieve statuses
+-------------------------------
+
+Base endpoint ics: ``/ocs/v2.php/apps/user_status/api/v1/statuses``
+
+Fetch a list of all set user-statuses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``GET``
+* Endpoint: ``/``
+* Data:
+
+    field | type | Description 
+    ------|------|------------
+    ``limit``  | int | Limit for pagination
+    ``offset`` | int | Offset for pagination
+
+* Response:
+    - Status code:
+        + ``200 OK``
+
+Fetch a specific user's status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Required capability: ``user_status``
+* Method: ``GET``
+* Endpoint: ``/{userId}``
+* Response:
+    - Status code:
+        + ``200 OK``
+        + ``404 Not Found`` If the user does not have a status set
+
+Files Sharing 
+^^^^^^^^^^^^^
+
+The user-status is also exposed via the following Files Sharing APIs:
+ * ``GET /ocs/v2.php/apps/files_sharing/api/v1/sharees``
+ * ``GET /ocs/v2.php/apps/files_sharing/api/v1/sharees_recommended``
+ * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares``
+ * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/inherited``
+ * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/pending``
+ * ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}``
+ * ``POST /ocs/v2.php/apps/files_sharing//api/v1/shares``
+ * ``PUT /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}``