diff --git a/.gitignore b/.gitignore index f5c18cb03da..dd39a2d53f2 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,9 @@ _build developer_manual/html_css_design/img developer_manual/html_css_design/icons.txt +# OpenAPI file +developer_manual/_static/openapi.json + # Exclude Eclipse project .project @@ -47,4 +50,4 @@ venv .history/ # JetBrains IDEs -.idea/ \ No newline at end of file +.idea/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000000..783d98b5ca6 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "build/openapi-extractor"] + path = build/openapi-extractor + url = https://github.com/nextcloud/openapi-extractor diff --git a/Makefile b/Makefile index 7785b221614..ae49bc64d72 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ user-manual-html: @echo "User manual build finished; HTML is updated" # Should also build icons-docs, but due to https://github.com/nextcloud/documentation/issues/7162 it is disabled -developer-manual-html: #icons-docs +developer-manual-html: openapi-spec #icons-docs rm -rf developer_manual/_build/html/com cd developer_manual && make html @echo "Developer manual build finished; HTML is updated" @@ -27,8 +27,15 @@ user-manual-pdf: cd user_manual && make latexpdf @echo "User manual build finished; PDF is updated" -#icons-docs: clean-icons-docs -# cd build && sh get-server-sources.sh $(DRONE_BRANCH) +get-server-sources: + cd build && sh get-server-sources.sh $(DRONE_BRANCH) + +openapi-spec: get-server-sources + git submodule update --init + cd build/openapi-extractor && composer install + cd build && sh generate-openapi.sh + +#icons-docs: clean-icons-docs get-server-sources # cd build && composer install && composer update # cd build && php generateIconsDoc.php diff --git a/build/generate-openapi.sh b/build/generate-openapi.sh new file mode 100644 index 00000000000..5d3dd1a587f --- /dev/null +++ b/build/generate-openapi.sh @@ -0,0 +1,16 @@ +#!/bin/bash +set -euxo pipefail + +./openapi-extractor/merge-specs \ + --core server/core/openapi.json \ + --merged ../developer_manual/_static/openapi.json \ + server/apps/cloud_federation_api/openapi.json \ + server/apps/dashboard/openapi.json \ + server/apps/dav/openapi.json \ + server/apps/files_sharing/openapi.json \ + server/apps/oauth2/openapi.json \ + server/apps/provisioning_api/openapi.json \ + server/apps/settings/openapi.json \ + server/apps/theming/openapi.json \ + server/apps/user_status/openapi.json \ + server/apps/weather_status/openapi.json diff --git a/build/openapi-extractor b/build/openapi-extractor new file mode 160000 index 00000000000..13d22c9cc3c --- /dev/null +++ b/build/openapi-extractor @@ -0,0 +1 @@ +Subproject commit 13d22c9cc3cbaa138d7268d48152b74bc4eeda33 diff --git a/developer_manual/_static/openapi.html b/developer_manual/_static/openapi.html new file mode 100644 index 00000000000..8ec85069fc3 --- /dev/null +++ b/developer_manual/_static/openapi.html @@ -0,0 +1,10 @@ + + + OCS API + + + + + + + diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst index 00d7136b50a..c650b98cbf4 100644 --- a/developer_manual/client_apis/OCS/index.rst +++ b/developer_manual/client_apis/OCS/index.rst @@ -4,12 +4,14 @@ OCS API =============================== -.. toctree:: - - ocs-api-overview - ocs-share-api - ocs-sharee-api - ocs-status-api - ocs-recommendations-api - ocs-user-preferences-api - ocs-translation-api +To browse the OCS API documentation please go `here <../../_static/openapi.html>`_. + +Notifications API +----------------- + +There is also the `Notifications API `_ + +Activity API +------------ + +Find the documentation in the `Activity app repo `__. diff --git a/developer_manual/client_apis/OCS/ocs-api-overview.rst b/developer_manual/client_apis/OCS/ocs-api-overview.rst deleted file mode 100644 index 52b444a5358..00000000000 --- a/developer_manual/client_apis/OCS/ocs-api-overview.rst +++ /dev/null @@ -1,239 +0,0 @@ -================= -OCS APIs overview -================= - -This document provides a quick overview of the OCS API endpoints supported in Nextcloud. - -All requests need to provide authentication information, either as a Basic Auth header or by passing a set of valid session cookies, if not stated otherwise. - - -Testing requests with curl --------------------------- - -All OCS requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PUT`, etc) and setting a request body where needed. - -For example: you can perform a :code:`GET` request to get information about a user: - - -.. code-block:: bash - - curl -u username:password -X GET 'https://cloud.example.com/ocs/v1.php/...' -H "OCS-APIRequest: true" - - -User metadata -------------- - -Since: 11.0.2, 12.0.0 - -This request returns the available metadata of a user. Admin users can see the information of all users, while a default user only can access their own metadata. - -.. code:: - - GET /ocs/v1.php/cloud/users/USERID - - -.. code:: xml - - - - - ok - 100 - OK - - - - - 1 - /path/to/storage/location/userid - userid - 1578283711000 - Database - - - 20632824998 - 842011482 - 21474836480 - 3.92 - 21474836480 - - user@foo.de - John Doe - John Doe - -
- https://example.com - - - 1st group - 2nd group - 3rd group - ... group - - de - de_DE - - 1 - 1 - - - - - -User metadata - List user IDs ------------------------------ - -This request returns a list containing all user IDs. Only admin users can query the list. - -.. code:: - - GET /ocs/v1.php/cloud/users - - -.. code:: xml - - - - - ok - 100 - OK - - - - - - 1st_user - 2nd_user - 3rd_user - ..._user - - - - - - -Capabilities API ----------------- - -Clients can obtain capabilities provided by the Nextcloud server and its apps via the capabilities OCS API. - -.. code:: - - GET /ocs/v1.php/cloud/capabilities - - - -.. code:: xml - - - - - ok - 100 - OK - - - - - - 17 - 0 - 2 - 17.0.2 - - - - - - 60 - remote.php/webdav - - - - - - -Theming capabilities --------------------- - -Values of the theming app are exposed through the capabilities API, allowing client developers to adjust the look of clients to the theming of different Nextcloud instances. - -.. code:: xml - - - Nextcloud - https://nextcloud.com - A safe home for all your data - #0082c9 - #ffffff - #0082c9 - #aaaaaa - #555555 - http://cloud.example.com/index.php/apps/theming/logo?v=1 - http://cloud.example.com/index.php/apps/theming/logo?v=1 - - - - -For elements like radio buttons, input borders and more, instead of the primary ``color`` value, the ``color-element-bright`` should be used on bright background and ``color-element-dark`` on dark background. -This when the primary color is e.g. set to ``#000000`` the ``color-elemenet-dark`` will be set to ``#555555`` so items are still visible. In the Nextcloud web UI only the top header uses ``color``, everything else uses ``color-element-*``. -Text and icons on these elements should use ``color-text``. - - -The background value can either be an URL to the background image or a hex color value. - -Direct Download ---------------- - -It might be required to give a 3rd party access to a file however you do not -want to hand over credentials to the 3rd party. An example of this is playing -files in an external media player on mobile devices. - -To solve this issue there is a way to request a unique public link to a single file. -This link will be valid for 8 hours afterwards it will be removed. - -To obtain a direct link: - -.. code:: - - POST /ocs/v2.php/apps/dav/api/v1/direct - -With the :code:`fileId` in the body (so :code:`fileId=42` for example). -This will then return you the link to use to obtain the file. - -Notifications -------------- - -There is also the `Notifications API `_ -As well as documentation on how to `Register a device for push notifications `_ - -Auto-complete and user search ------------------------------ - -It is possible to search for users using the auto-complete API, used to auto-complete usernames in comments, chat or to find guest accounts. The code `can be found here `_ - -An example curl command would be: - -.. code:: - - curl -i -u master -X GET -H "OCS-APIRequest: true" 'https://my.nextcloud/ocs/v2.php/core/autocomplete/get?search=JOANNE%40EMAIL.ISP&itemType=%20&itemId=%20&shareTypes[]=8&limit=2' - -That would look for JOANNE@EMAIL.ISP as guest user. Maximum 2 results to be returned for a regular user, the -shareTypes array would carry only "8". ``itemType`` and ``itemId`` are left out (set to a white space), -essentially they are to give context about the use case, so sorters can do their work (like who commented last). -It can be an option for filtering on a later stage but you can also leave them out as per the below example. - -.. code:: - - curl -i -u master -X GET -H "OCS-APIRequest: true" 'https://my.nextcloud/ocs/v2.php/core/autocomplete/get?search=JOANNE%40EMAIL.ISP&shareTypes[]=8&limit=2' - -The shareType defaults to regular users if you left it out), the limit defaults to 10. - -Filtering the auto-complete results -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In case needed, you can also further filter the auto-complete results on the PHP side using the -``OCP\Collaboration\AutoComplete\AutoCompleteEvent`` event. The event gives you access to the current -result set, the item and share types and some more information that you can use to e.g. limit the autocomplete -results to users that are actually in the current chat conversation. diff --git a/developer_manual/client_apis/OCS/ocs-recommendations-api.rst b/developer_manual/client_apis/OCS/ocs-recommendations-api.rst deleted file mode 100644 index 2b300e49921..00000000000 --- a/developer_manual/client_apis/OCS/ocs-recommendations-api.rst +++ /dev/null @@ -1,41 +0,0 @@ -======================= -OCS Recommendations API -======================= - -The OCS Recommendations API allows you to get a list of recommended files and folders with recent activity. - -.. note:: This API requires the Recommendations app to be enabled. - -The base URL for all calls to the share API is: */ocs/v2.php/apps/recommendations/api/v1/* - -All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. - -.. warning:: This API is **experimental** and can change in the future without further notice! - - -Recommendations - Retrieval ---------------------------- - -Fetch user-controlled recommendations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* Method: ``GET`` -* Endpoint: ``/recommendations`` -* Response: - - Status code: - + ``200 OK`` -* Result: - - `enabled` (boolean) True if recommendations are enabled for user. False otherwise. - - `recommendations` (list, optional) List of recommended files and folders, if the user enabled recommendations. - -Fetch user setting and recommendations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* Method: ``GET`` -* Endpoint: ``/recommendations/always`` -* Response: - - Status code: - + ``200 OK`` -* Result: - - `enabled` (boolean) True if recommendations are enabled for user. False otherwise. - - `recommendations` (list) List of recommended files and folders, independent of the users decision. \ No newline at end of file diff --git a/developer_manual/client_apis/OCS/ocs-share-api.rst b/developer_manual/client_apis/OCS/ocs-share-api.rst deleted file mode 100644 index caa3d4f0fdf..00000000000 --- a/developer_manual/client_apis/OCS/ocs-share-api.rst +++ /dev/null @@ -1,276 +0,0 @@ -============= -OCS Share API -============= - -The OCS Share API allows you to access the sharing API from outside over -pre-defined OCS calls. - -The base URL for all calls to the share API is: */ocs/v2.php/apps/files_sharing/api/v1* - -All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. - -Local Shares ------------- - -Get all Shares -^^^^^^^^^^^^^^ - -Get all shares from the user. - -* Syntax: /shares -* Method: GET - -* Result: XML with all shares - -Statuscodes: - -* 100 - successful -* 404 - couldn't fetch shares - -Get Shares from a specific file or folder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get all shares from a given file/folder. - -* Syntax: /shares -* Method: GET - -* URL Arguments: path - (string) path to file/folder -* URL Arguments: reshares - (boolean) returns not only the shares from the current user but all shares from the given file. -* URL Arguments: subfiles - (boolean) returns all shares within a folder, given that - *path* defines a folder -* Mandatory fields: path - -* Result: XML with the shares - -Statuscodes: - -* 100 - successful -* 400 - not a directory (if the 'subfile' argument was used) -* 404 - file doesn't exist - -Get information about a known Share -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get information about a given share. - -* Syntax: /shares/** -* Method: GET - -* Arguments: share_id - (int) share ID - -* Result: XML with the share information - -Statuscodes: - -* 100 - successful -* 404 - share doesn't exist - -Create a new Share -^^^^^^^^^^^^^^^^^^ - -Share a file/folder with a user/group or as public link. - -* Syntax: /shares -* Method: POST - -* POST Arguments: path - (string) path to the file/folder which should be shared -* POST Arguments: shareType - (int) 0 = user; 1 = group; 3 = public link; 4 = email; 6 = federated cloud share; 7 = circle; 10 = Talk conversation -* POST Arguments: shareWith - (string) user / group id / email address / circleID / conversation name with which the file should be shared -* POST Arguments: publicUpload - (string) allow public upload to a public shared folder (true/false) -* POST Arguments: password - (string) password to protect public link Share with -* POST Arguments: permissions - (int) 1 = read; 2 = update; 4 = create; 8 = delete; - 16 = share; 31 = all (default: 31, for public shares: 1) -* POST Arguments: expireDate - (string) set a expire date for public link - shares. This argument expects a well formatted date string, e.g. 'YYYY-MM-DD' -* POST Arguments: note - (string) Adds a note for the share recipient. -* POST Arguments: attributes - (string) URI-encoded serialized JSON string for :ref:`share attributes` -* Mandatory fields: shareType, path and shareWith for shareType 0 or 1. - -* Result: XML containing the share ID (int) of the newly created share - -Statuscodes: - -* 100 - successful -* 400 - unknown share type -* 403 - public upload was disabled by the admin -* 404 - file couldn't be shared - -Delete Share -^^^^^^^^^^^^ - -Remove the given share. - -* Syntax: /shares/** -* Method: DELETE - -* Arguments: share_id - (int) share ID - -Statuscodes: - -* 100 - successful -* 404 - file couldn't be deleted - -Update Share -^^^^^^^^^^^^ - -Update a given share. Only one value can be updated per request. - -* Syntax: /shares/** -* Method: PUT - -* Arguments: share_id - (int) share ID -* PUT Arguments: permissions - (int) update permissions (see "Create share" - above) -* PUT Arguments: password - (string) updated password for public link Share -* PUT Arguments: publicUpload - (string) enable (true) /disable (false) public - upload for public shares. -* PUT Arguments: expireDate - (string) set a expire date for public link - shares. This argument expects a well formatted date string, e.g. 'YYYY-MM-DD' -* PUT Arguments: note - (string) Adds a note for the share recipient. -* PUT Arguments: attributes - (string) serialized JSON string for :ref:`share attributes` - -.. note:: Only one of the update parameters can be specified at once. - -Statuscodes: - -* 100 - successful -* 400 - wrong or no update parameter given -* 403 - public upload disabled by the admin -* 404 - couldn't update share - -.. _Share attributes: - -Share attributes -^^^^^^^^^^^^^^^^ - -Share attributes are used for more advanced flags like permissions. - -To remove the download permission from a share, use the following serialized string in the "attributes" parameter: - -.. code-block:: json - - [ - {"scope":"permissions","key":"download","enabled":false} - ] - -This will prevent users from downloading the files from the share. -For specific file types like office files, it will still be possible to view the files using the appropriate viewer app, -which itself will present the file in a way that downloading will not be allowed. - -By default when unset, the "download" attribute will be true and so the download permission will be granted. - -.. note:: There is currently only one share attribute "download" from the scope "permissions". - This attribute is only valid for user and group shares, not for public link shares. - -Federated Cloud Shares ----------------------- - -Both the sending and the receiving instance need to have federated cloud sharing -enabled and configured. See `Configuring Federated Cloud Sharing `_. - -.. TODO ON RELEASE: Update version number above on release - -Create a new Federated Cloud Share -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Creating a federated cloud share can be done via the local share endpoint, using -(int) 6 as a shareType and the `Federated Cloud ID `_ -of the share recipient as shareWith. See `Create a new Share`_ for more information. - - -List accepted Federated Cloud Shares -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get all federated cloud shares the user has accepted. - -* Syntax: /remote_shares -* Method: GET - -* Result: XML with all accepted federated cloud shares - -Statuscodes: - -* 100 - successful - -Get information about a known Federated Cloud Share -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get information about a given received federated cloud that was sent from a remote instance. - -* Syntax: /remote_shares/** -* Method: GET - -* Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares`` list - -* Result: XML with the share information - -Statuscodes: - -* 100 - successful -* 404 - share doesn't exist - -Delete an accepted Federated Cloud Share -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Locally delete a received federated cloud share that was sent from a remote instance. - -* Syntax: /remote_shares/** -* Method: DELETE - -* Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares`` list - -* Result: XML with the share information - -Statuscodes: - -* 100 - successful -* 404 - share doesn't exist - -List pending Federated Cloud Shares -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get all pending federated cloud shares the user has received. - -* Syntax: /remote_shares/pending -* Method: GET - -* Result: XML with all pending federated cloud shares - -Statuscodes: - -* 100 - successful - -Accept a pending Federated Cloud Share -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Locally accept a received federated cloud share that was sent from a remote instance. - -* Syntax: /remote_shares/pending/** -* Method: POST - -* Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares/pending`` list - -* Result: XML with the share information - -Statuscodes: - -* 100 - successful -* 404 - share doesn't exist - -Decline a pending Federated Cloud Share -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Locally decline a received federated cloud share that was sent from a remote instance. - -* Syntax: /remote_shares/pending/** -* Method: DELETE - -* Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares/pending`` list - -* Result: XML with the share information - -Statuscodes: - -* 100 - successful -* 404 - share doesn't exist diff --git a/developer_manual/client_apis/OCS/ocs-sharee-api.rst b/developer_manual/client_apis/OCS/ocs-sharee-api.rst deleted file mode 100644 index 913ccf06e76..00000000000 --- a/developer_manual/client_apis/OCS/ocs-sharee-api.rst +++ /dev/null @@ -1,51 +0,0 @@ -============== -OCS Sharee API -============== - -The OCS Sharee API allows you to access the sharing API from outside over -pre-defined OCS calls. - -The base URL for all calls to the share API is: */ocs/v1.php/apps/files_sharing/api/v1* - -All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. - -Search ------- - -Search sharees -^^^^^^^^^^^^^^ - -Get all sharees matching a search term. - -* Syntax: /sharees -* Method: GET - -* URL Arguments: search - (string) the search term -* URL Arguments: lookup - (bool) whether to search globally on the Nextcloud lookup server -* URL Arguments: perPage - (int) number of sharees per page -* URL Arguments: itemType - (string) type of share, e.g. "file" - -* Result: XML with all sharees - -Status codes: - -* 100 - successful - -Recommendation --------------- - -Sharee recommendations -^^^^^^^^^^^^^^^^^^^^^^ - -Get sharees the sharer might want to share with. - -* Syntax: /sharees_recommended -* Method: GET - -* URL Arguments: itemType - (string) type of share, e.g. "file" - -* Result: XML with recommended sharees - -Status codes: - -* 100 - successful diff --git a/developer_manual/client_apis/OCS/ocs-status-api.rst b/developer_manual/client_apis/OCS/ocs-status-api.rst deleted file mode 100644 index 4be58a73440..00000000000 --- a/developer_manual/client_apis/OCS/ocs-status-api.rst +++ /dev/null @@ -1,192 +0,0 @@ -============== -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: */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 - -Fetch a user's backup status -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In some scenarios the user's status can be overwritten automatically, e.g. by joining a call in Nextcloud Talk, -or when the availability automation is enabled. In this case the userId can be prefixed with an `_` underscore, -to get the original user status. When a user status is returned and the ``user_status`` > ``restore`` capability -is available, the backup status should be added as an item in the predefined status list. Clicking that should then -do an API call to `User status - Restore backup`_ should be done. - -* Required capability: ``user_status`` -* Method: ``GET`` -* Endpoint: ``/_{userId}`` -* Response: - - Status code: - + ``200 OK`` - + ``404 Not Found`` If the user does not have a backup 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}`` - -User status - Restore backup ----------------------------- - -* Required capability: ``user_status`` > ``restore`` -* Method: ``DELETE`` -* Endpoint: ``/revert/{messageId}`` -* Response: - - Status code: - + ``200 OK`` diff --git a/developer_manual/client_apis/OCS/ocs-translation-api.rst b/developer_manual/client_apis/OCS/ocs-translation-api.rst deleted file mode 100644 index 1bc93ae178e..00000000000 --- a/developer_manual/client_apis/OCS/ocs-translation-api.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. _ocs-translation-api: - -=================== -OCS Translation API -=================== - -.. versionadded:: 26 - -The OCS Translation API allows you to translate strings from a language to another. - -The base URL for all calls to the share API is: */ocs/v2.php/translation/* - -All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. - - -Get available translation options ---------------------------------- - -.. versionadded:: 26 - -* Method: ``GET`` -* Endpoint: ``/languages`` -* Response: - - Status code: - + ``200 OK`` - - Data: - -+----------------------+--------+---------------------------------------------------------------------------------------------------+ -| field | type | Description | -+----------------------+--------+---------------------------------------------------------------------------------------------------+ -|``languageDetection`` | bool | Whether "from" language can be skipped as a translation provider supports detecting it from input | -+----------------------+--------+---------------------------------------------------------------------------------------------------+ -|``languages`` | array | A list of language tuples, see definition below | -+----------------------+--------+---------------------------------------------------------------------------------------------------+ - -Language tuple structure -^^^^^^^^^^^^^^^^^^^^^^^^ - -+--------------+--------+--------------------------------------------------------------+ -| field | type | Description | -+--------------+--------+--------------------------------------------------------------+ -|``from`` | string | ISO code of the "from" language | -+--------------+--------+--------------------------------------------------------------+ -|``fromLabel`` | string | Name of the "from" language that should be shown to the user | -+--------------+--------+--------------------------------------------------------------+ -|``to`` | string | ISO code of the "to" language | -+--------------+--------+--------------------------------------------------------------+ -|``toLabel`` | string | Name of the "to" language that should be shown to the user | -+--------------+--------+--------------------------------------------------------------+ - -Translate a string ------------------- - -.. versionadded:: 26 - -.. note:: The endpoint is rate limited as it can be quite resource intensive. Users can make 25 requests in 2 minutes, guests only 10 - -* Method: ``POST`` -* Endpoint: ``/translate`` -* Data: - -+-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| field | type | Description | -+-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|``text`` | string | The text to be translated | -+-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|``fromLanguage`` | string/null | The ISO code of the "from" language, when null is given and a translation provider allows detecting the source language it will be tried to guess it from the ``text`` input | -+-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|``toLanguage`` | string | The ISO code of the "to" language | -+-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -* Response: - - Status code: - + ``200 OK`` - + ``400 Bad Request`` - When the to language is not supported by any provider - + ``400 Bad Request`` - When the from language is not supported by any provider - + ``400 Bad Request`` - When the from language is not given, but no provider supports detecting the language - + ``412 Precondition Failed`` - When no translation provider is installed - + ``429 Too Many Requests`` - When the rate limiting was exceeded - - - Data: - + ``text`` - Only provided in case of ``200 OK``, the translated string - + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed - + ``from`` - The from language that was provided or detected from the input (can also be null or missing, when an error happens while detecting the language) diff --git a/developer_manual/client_apis/OCS/ocs-user-preferences-api.rst b/developer_manual/client_apis/OCS/ocs-user-preferences-api.rst deleted file mode 100644 index 6157e577acb..00000000000 --- a/developer_manual/client_apis/OCS/ocs-user-preferences-api.rst +++ /dev/null @@ -1,77 +0,0 @@ -======================== -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: */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/conf.py b/developer_manual/conf.py index 30dab465777..3bee486887f 100644 --- a/developer_manual/conf.py +++ b/developer_manual/conf.py @@ -126,7 +126,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['../_shared_assets/static'] +html_static_path = ['../_shared_assets/static', '_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/developer_manual/digging_deeper/translation.rst b/developer_manual/digging_deeper/translation.rst index 1d17b0a2975..0c231a7c4ad 100644 --- a/developer_manual/digging_deeper/translation.rst +++ b/developer_manual/digging_deeper/translation.rst @@ -18,7 +18,7 @@ To consume the Translation API, you will need to :ref:`inject` +If you would like to use the translation functionality in a client, there are also OCS endpoints available for this: :ref:`OCS Translation API` Implementing a Translation provider -----------------------------------