.. _api_webdav:

# WebDAV

RiskScape Platform storage is also reachable over
[WebDAV](https://en.wikipedia.org/wiki/WebDAV), an HTTP-based protocol for
reading and writing remote files.

.. note::
    This page is aimed at advanced users.
    If you just want to use WebDAV to manually transfer a few files between your computer
    and the Platform, see the :ref:`webdav_files` section of the
    :ref:`project_files` tutorial, which walks through setting up your
    operating system's file explorer as a WebDAV client.

RiskScape Platform's WebDAV API is is browsable and available at
https://riskscape.nz/dav - from there you can select:

- https://riskscape.nz/dav/projects will show you the :ref:`Project storage <input_files>`
for any Platform projects you belong to. This typically contains all the input
data and configuration that goes into RiskScape models. Projects are organized in
a _organization -> group -> project_ folder hierarchy.
- https://riskscape.nz/dav/users will show you any files in your own personal storage
on the Platform.

Clicking on a folder will show you the files and folders in that directory.
Clicking on a file will download the file in your browser.

## Authenticating

To access WebDAV from a script, you'll need
to use a WebDAV access token to authenticate.
Refer to :ref:`api_authentication` for how to create a WebDAV access token

The following examples assume that you have :ref:`setup an environment variable <setup_RISKSCAPE_TOKEN>`
called `RISKSCAPE_TOKEN` that contains your WebDAV token.
You can test whether your secret is setup correctly using the `curl` command:

```none
curl -u TOKEN:$RISKSCAPE_TOKEN https://riskscape.nz/dav
```

## Accessing WebDAV from Python

If you are writing a script, the `webdavclient3` [Python package](https://pypi.org/project/webdavclient3)
is a straightforward way to talk to WebDAV. To install `webdavclient3`, use:

```none
pip install webdavclient3
```

Then a simple Python script to connect via the WebDAV API and download a file might look like this:

```python
import os

from webdav3.client import Client

options = {
    "webdav_hostname": "https://riskscape.nz/dav/projects",
    "webdav_login": "TOKEN",
    "webdav_password": os.environ["RISKSCAPE_TOKEN"],
}
client = Client(options)

# list what is available at the top level
print(client.list())

# download a file from a project
client.download_sync(
    remote_path="riskscape/example/getting-started/README.md",
    local_path="README.md",
)
```

.. note::
    ``webdavclient3`` authenticates with HTTP Basic authentication by
    default, so the same ``TOKEN`` username and access token password
    apply here too.

## Accessing WebDAV with Rclone

[Rclone](https://rclone.org/) is a command-line tool for copying and
syncing files, with built-in support for WebDAV.

Create a remote for RiskScape Platform:

```none
rclone config create riskscape webdav \
  url=https://riskscape.nz/dav/projects \
  vendor=other \
  user=TOKEN \
  pass=$RISKSCAPE_TOKEN \
  --obscure
```

.. note::
    The ``--obscure`` flag tells Rclone to obscure the plain-text password
    before storing it in its configuration file. Without it, Rclone expects the
    password to already be obscured.

Once the remote is set up, you can list and copy files:

```none
rclone lsf riskscape:riskscape/example/getting-started

rclone copy riskscape:riskscape/example/getting-started/README.md .
```

.. tip::
    Setting up Rclone like this is a handy way to keep a local CLI project in sync with the
    RiskScape Platform. Rclone has a ``--dry-run`` option to show you what would be copied,
    and options to exclude copying unnecessary files, e.g ``--exclude ".jython_cache/**" --exclude "**/__pycache__/**" --exclude "output/**"``.

## Further reading

- :ref:`api_authentication` covers access tokens in more detail.
- :ref:`webdav_files` walks through connecting a file explorer to WebDAV,
  with screenshots.