.. Netfiles API documentation master file, created by
   sphinx-quickstart on Fri Mar  6 11:42:21 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Datarooms
=========

Each user can have access to as many datarooms as there are on the Netfiles system.

Once you identify a user using :doc:`Check Identity <calls/checkidentity>`, you will receive 
the list of the user's datarooms. For each dataroom there will be an attribute called ``AccessAllowed``.
If that attribute is set to ``true``, you can download the contents of that dataroom *at least on a single level*
(i.e. you can download the direct children of the dataroom).

Since that attribute is valid for every *Hyperwave Object*, you should check it every time you download the children
of a given item.

Anyhow, getting the children of the dataroom itself is somewhat not straight-forward.

Let's assume the following items:

1. We are the 'iPad'-App
2. We login as user 'john' with the password 'doe'
3. The user has access to three datarooms: (a) Test, (b) Private and (c) Business
4. The user is not allowed to access the dataroom "Business" using "iPad"-App

When we make the :doc:`Check Identity Call <calls/checkidentity>`, we receive a JSON structure.

In the ``projects`` attribute of the ``response``-json, we get an array of three ``projects`` (datarooms). Below
only the relevant parts of each dataroom are shown:

.. code:: 

    {
        "response": {
            "id" : "uid-...",
            ...
            },
            ...
            "projects": [
                {
                    "id"   : "ID-...",
                    ...
                    "path" : "/test",
                    "name" : "/test",
                    "title": "John's Test Dataroom",
                    "AccessAllowed": true
                },
                {
                    "id"   : "ID-...",
                    ...
                    "path" : "/private",
                    "name" : "/private",
                    "title": "John's Private Dataroom",
                    "AccessAllowed": true
                },
                {
                    "id"   : "ID-...",
                    ...
                    "path" : "/acmeincbusiness",
                    "name" : "/acmeincbusiness",
                    "title": "ACME Inc Business",
                    "AccessAllowed": false
                }
            ]
        }
    }

In order to get the content (children) of any of the datarooms, we need to first get the list of the children.

The command for this is :doc:`Get Children <calls/getchildren>`.

But, the original documentation says that we need to provide the ID of the dataroom in question as the 
``Object-Path``, which is **wrong**. But trying any one of ``path`` or ``name`` doesn't work either. Each time we try, 
we get an error message from the server.

The right path to provide is ``<dataroomname>/projectfiles``.

So, you correct ``getChildren``-Call to get the children of *John's Private Dataroom* is:

::

  GET https://app.netfiles.de/private/projectfiles;internal&action=json&apikey=<myAPIKey>&deviceID=<currentDeviceID>&method=getChildren
  Authorization: Basic BASE64(UTF8Bytes("john:doe"))
  Accept: application/json
  User-Agent: iPad
  netfiles: <value of the netfiles cookie>
  sk1: <value of the sk1 cookie>
  HW_User: <value of the HW_User cookie>
  HyperwaveSession: <value of the HyperwaveSession cookie>
  sk_s_web_S: <value of the sk_s_web_S cookie>
  sk_p_web_S: <value of the sk_p_web_S cookie>