=======
Folders
=======

.. contents::

Folder model
============

.. object:: Folder

   :param int id: The folder's unique id
   :param string title: The humanly-readable label for the folder
   :param int parent_folder: The folder's parent folder
   :param string userId: The user ID of the nextcloud account that owns this folder
   :param string userDisplayName: The name of the nextcloud account that owns this folder

      .. versionadded:: 12.1.0

   .. note::

      The root folder has the magic id ``-1``, which is the same for every user.


Get full folder hierarchy
=========================

.. get:: /public/rest/v2/folder

   :synopsis: Retrieve the folder hierarchy

   .. versionadded:: 0.15.0

   :query int root: The id of the folder whose contents to retrieve (Default: ``-1``, which is the root folder)
   :query int layers: How many layers of folders to return at max. By default, all layers are returned.

   :>json string status: ``success`` or ``error``
   :>json array data: The folder hierarchy

   :>jsonarr int id: The id of the folder
   :>jsonarr string title: the folder title
   :>jsonarr int parent_folder: the folder's parent folder
   :>jsonarr array children: The folder's children (folders only)

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success", "data": [
          {"id": 1, "title": "work", "parent_folder": -1},
          {"id": 2, "title": "personal", "parent_folder": -1, "children": [
            {"id": 3, "title": "garden", "parent_folder": 2},
            {"id": 4, "title": "music", "parent_folder": 2}
          ]},
        ]
      }

Get single folder
=================

.. get:: /public/rest/v2/folder/(int:id)

   :synopsis: Retrieve a single folder

   .. versionadded:: 0.15.0

   :>json string status: ``success`` or ``error``
   :>json object item: The retrieved folder

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/2 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "item": {
          "id": 2,
          "title": "My Personal Bookmarks",
          "parent_folder": -1
        }
      }


Create a folder
===============

.. post:: /public/rest/v2/folder

   :synopsis: Create a new folder

   .. versionadded:: 0.15.0

   :<json string title: The title of the new folder, defaults to ""
   :<json int parent_folder: The id of the parent folder for the new folder, defaults to -1

   :>json string status: ``success`` or ``error``
   :>json object item: The new folder

   **Example:**

   .. sourcecode:: http

      POST /index.php/apps/bookmarks/public/rest/v2/folder HTTP/1.1
      Host: example.com
      Accept: application/json

      {"title": "sports", "parent_folder": "-1"}

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "item": {
          "id": 5,
          "title": "sports",
          "parent_folder": "-1"
        }
      }

Edit a folder
=============

.. put:: /public/rest/v2/folder/(int:id)

   :synopsis: Edit an existing folder

   .. versionadded:: 0.15.0

   :<json string title: The title of the new folder
   :<json int parent_folder: The id of the parent folder of the folder

   :>json string status: ``success`` or ``error``
   :>json object item: The new folder

   **Example:**

   .. sourcecode:: http

      POST /index.php/apps/bookmarks/public/rest/v2/folder/5 HTTP/1.1
      Host: example.com
      Accept: application/json

      {"title": "optional physical activity"}

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "item": {
          "id": 5,
          "title": "optional physical activity",
          "parent_folder": -1
        }
      }

Hash a folder
=============

.. get:: /public/rest/v2/folder/(int:id)/hash

   :synopsis: Compute the hash of a folder

   .. versionadded:: 1.0.0

   :param array fields: All bookmarks fields that should be hashed (default: ``title``, ``url``)

   :>json string status: ``success`` or ``error``
   :>json string data: The SHA256 hash in hexadecimal notation

   This endpoint is useful for synchronizing data between the server and a client. By comparing the hash of the data on your client with the hash from the server you can figure out which parts of the tree have changed.

   The algorithm works as follows:

    - Hash endpoint: return ``hashFolder(id, fields)``
    - ``hashFolder(id, fields)``

      - set ``childrenHashes`` to empty array
      - for all children of the folder

        - if it's a folder

          - add to ``childrenHashes``: ``hashFolder(folderId, fields)``

        - if it's a bookmark

          - add to ``childrenHashes``: ``hashBookmark(bookmarkId, fields)``

      - set ``object`` to an empty dictionary
      - set ``object[title]`` to the title of the folder, if this is not the root folder
      - set ``object[children]`` to the value of ``childrenHashes``
      - set ``json`` to ``to_json(object)``
      - Return ``sha256(json)``

    - ``hashBookmark(id, fields)``

      - set ``object`` to an empty dictionary/hashmap
      - for all entries in ``fields``

        - set ``object[field]`` to the value of the associated field of the bookmark

      - Return ``sha256(to_json(object))``

    - ``to_json``: A JSON stringification algorithm that adds no unnecessary white-space and doesn't use JSON's backslash escaping unless necessary (character set is UTF-8)
    - ``sha256``: The SHA-256 hashing algorithm

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/5/hash HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      { "status": "success", "data": "6543a23c78aefd0274f3ac98de98723" }

Delete a folder
===============

.. delete:: /public/rest/v2/folder/(int:id)

   :synopsis: Delete a folder

   .. versionadded:: 0.15.0

   :>json string status: ``success`` or ``error``
   :>json object item: The new folder

   **Example:**

   .. sourcecode:: http

      DELETE /index.php/apps/bookmarks/public/rest/v2/folder/5 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success"
      }

Add bookmark to folder
======================

.. post:: /public/rest/v2/folder/(int:folder_id)/bookmarks/(int:bookmark_id)

   :synopsis: Add a bookmark to a folder

   .. versionadded:: 0.15.0

   :>json string status: ``success`` or ``error``

   **Example:**

   .. sourcecode:: http

      POST /index.php/apps/bookmarks/public/rest/v2/folder/5/bookmarks/418 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success"
      }

Remove bookmark from folder
===========================

.. delete:: /public/rest/v2/folder/(int:folder_id)/bookmarks/(int:bookmark_id)

   :synopsis: Remove a bookmark from a folder

   .. versionadded:: 0.15.0

   :>json string status: ``success`` or ``error``

   If this is the only folder this bookmark resides in, the bookmark will be deleted entirely.

   **Example:**

   .. sourcecode:: http

      DELETE /index.php/apps/bookmarks/public/rest/v2/folder/5/bookmarks/418 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success"
      }

Get folder's content order
==========================

.. get:: /public/rest/v2/folder/(int:folder_id)/childorder

   :synopsis: Retrieve the order of contents of a folder

   .. versionadded:: 0.15.0

   :query int layers: The number of tree layers to return, defaults to 0 which returns only the immediate children

   :>json string status: ``success`` or ``error``
   :>json array data: An ordered list of child items

   :>jsonarr string type: Either ``folder`` or ``bookmark``
   :>jsonarr string id: The id of the bookmark or folder
   :>jsonarr array children: In case more than one layers are returned, folders will have a this additional property with an array containing more items (or none)

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "data": [
          {"type": "folder", "id": 17},
          {"type": "bookmark", "id": 204},
          {"type": "bookmark", "id": 192},
          {"type": "bookmark", "id": 210}
        ]
      }

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder?layers=1 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "data": [
          {"type": "folder", "id": 17, "children": [
              {"type": "bookmark", "id": 234},
              {"type": "bookmark", "id": 492},
              {"type": "bookmark", "id": 250},
              {"type": "folder", "id": 18 }
            ]
          },
          {"type": "bookmark", "id": 204},
          {"type": "bookmark", "id": 192},
          {"type": "bookmark", "id": 210}
        ]
      }

Set folder's content order
==========================

.. patch:: /public/rest/v2/folder/(int:folder_id)/childorder

   :synopsis: Set the order of contents of a folder

   .. versionadded:: 0.15.0

   :<json array data: An ordered list of child items

   :<jsonarr string type: Either ``folder`` or ``bookmark``
   :<jsonarr string id: The id of the bookmark or folder

   :>json string status: ``success`` or ``error``

   **Example:**

   .. sourcecode:: http

      PATCH /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder HTTP/1.1
      Host: example.com
      Accept: application/json

      {
        "status": "success",
        "data": [
          {"type": "folder", "id": 17},
          {"type": "bookmark", "id": 204},
          {"type": "bookmark", "id": 192},
          {"type": "bookmark", "id": 210}
        ]
      }

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success"
      }

Get folder's contents
=====================

.. get:: /public/rest/v2/folder/(int:folder_id)/children

   :synopsis: Retrieve all of a folder's contents (with varying depth)

   .. versionadded:: 3.0.0

   :query int layers: How many layers of descendants to return at max. Defaults to 0, retuning only immediate children.

   :>json string status: ``success`` or ``error``
   :>json array data: An ordered list of child items

   :>jsonarr string type: Either ``folder`` or ``bookmark``
   :>jsonarr string id: The id of the bookmark or folder

   If the type of the item is ``folder``

   :>jsonarr int id: The id of the folder
   :>jsonarr string title: The title of the folder
   :>jsonarr string userId: The owner of the folder
   :>jsonarr array children: The children of the folder. This is only set, when the number of layers to return includes this folder.

   If the type of the item is ``bookmark`` it will have all properties of the Bookmark type (see :ref:`bookmark`).

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/5/children HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "data": [
          {"type": "folder", "id": "17", "title": "foo", "userId": "admin"},
          {"type": "bookmark", "id": "204", "title": "Nextcloud", "url": "https://nextcloud.com/"},
          {"type": "bookmark", "id": "204", "title": "Google", "url": "https://google.com/"},
        ]
      }


Get folder's content count
=====================

.. get:: /public/rest/v2/folder/(int:folder_id)/count

   :synopsis: Retrieve the number of bookmarks contained in this folder and all descendants

   .. versionadded:: 3.4.0

   :>json string status: ``success`` or ``error``
   :>json int item: The number of descendant bookmarks

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/5/count HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "item": 512
      }

Get public token
================

.. get:: /public/rest/v2/folder/(int:folder_id)/publictoken

   :synopsis: Retrieve the public token of a folder that has been shared via a public link. This will return a 404 if the folder has no public token yet.

   .. versionadded:: 3.0.0

   :>json string status: ``success`` or ``error``
   :>json string item: The public token

   To use the token either make API requests with it (see :ref:`authentication`). Or point your browser to ``https://yournextcloud.com/index.php/apps/bookmarks/public/{token}``

   **Example:**

   .. sourcecode:: http

      GET /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "item": "dk3J8Qm"
      }

Create public token
================

.. post:: /public/rest/v2/folder/(int:folder_id)/publictoken

   :synopsis: Create a public link for a folder

   .. versionadded:: 3.0.0

   :>json string status: ``success`` or ``error``
   :>json string item: The token that can be used to access the folder publicly.

   **Example:**

   .. sourcecode:: http

      POST /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "item": "dk3J8Qm"
      }

Delete public token
===================

.. delete:: /public/rest/v2/folder/(int:folder_id)/publictoken

   :synopsis: Remove the public link for a folder

   .. versionadded:: 3.0.0

   :>json string status: ``success`` or ``error``

   **Example:**

   .. sourcecode:: http

      POST /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1
      Host: example.com
      Accept: application/json

   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
      }

Import bookmarks into folder
============================

.. post:: /public/rest/v2/folder/(int:folder_id)/import

   :synopsis: Import an HTML bookmarks file into a folder. Returns the newly created items.

   .. versionadded:: 1.1.0

   :formparam bm_import: The HTML file to be uploaded

   **Example:**

   .. sourcecode:: http

      POST /index.php/apps/bookmarks/public/rest/v2/folder/-1/import HTTP/1.1
      Host: example.com
      Content-Length: 5038
      Content-Type: multipart/form-data; boundary=------------------------8c1687317cdae5bf

      --------------------------8c1687317cdae5bf
      Content-Disposition: form-data; name="bm_import"; filename="bookmarks.html"
      Content-Type: text/html

      <html>
      ...


   **Response:**

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "status": "success",
        "data": [
          {"type": "folder", "id": "17", "title": "foo", "children": [
              {"type": "folder", "id": 18, "title": "bla", "children": [] }
              {"type": "bookmark", "id": 234, "title": "Gnome", "url": "https://www.gnome.org"},
              {"type": "bookmark", "id": 492, "title": "kernel", "url": "https://www.kernel.org"},
              {"type": "bookmark", "id": 250, "title": "Test", "url": "https://www.test.de"},
              {"type": "folder", "id": 18, "title": "foobar" "children": [] }
            ]
          },
          {"type": "bookmark", "id": "204", "title": "Nextcloud", "url": "https://nextcloud.com/"},
          {"type": "bookmark", "id": "205", "title": "Google", "url": "https://google.com/"},
        ]
      }