Document the public-files WebDAV API endpoint

modules/developer_manual/examples/core/scripts/curl/dav/public_files/view_public_link.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+##
+## Variable Declaration
+##
+API_PATH="/remote.php/dav/public-files/<share_token>"
+SERVER_URI="{oc-examples-server-url}"
+REQUEST_BODY=$(cat <<EOF                                                                
+<?xml version="1.0"?>                                 
+<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
+    <d:prop>   
+        <oc:public-link-item-type />
+        <oc:public-link-item-permission />
+        <oc:public-link-item-expiration />
+        <oc:public-link-item-share-datetime />
+        <oc:public-link-item-owner />
+    </d:prop>
+</d:propfind>
+EOF
+)
+
+curl "'$SERVER_URI/$API_PATH" \
+    -H 'Content-Type: application/xml; charset=UTF-8' \
+    -H 'Depth: 1' \
+    -X PROPFIND \
+    --data-binary "${REQUEST_BODY}"

modules/developer_manual/examples/core/scripts/php/dav/public_files/view_public_link.php

@@ -0,0 +1,23 @@
+<?php
+
+use GuzzleHttp\Client;
+
+require_once('vendor/autoload.php');
+
+// Configure the basic client
+$client = new Client([
+    'base_uri' => '{oc-examples-server-url}/remote.php/dav/',
+]);
+
+$share_token = '<share_token>';
+
+try {
+    $response = $client->request('PROPFIND', "public-files/${share_token}", [
+        'headers' => [
+            'Content-Type'=> 'text/xml',
+        ],
+    ]);
+    print $response->getBody()->getContents();
+} catch (\GuzzleHttp\Exception\ClientException $e) {
+    print $e->getMessage();
+}

modules/developer_manual/examples/core/webdav_api/public_files/response/listing-members-is-disabled.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
+  <s:exception>Sabre\DAV\Exception\MethodNotAllowed</s:exception>
+  <s:message>Listing members of this collection is disabled</s:message>
+</d:error>

modules/developer_manual/examples/core/webdav_api/public_files/response/no-read-privileges-on-public-link.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
+  <s:exception>Sabre\DAVACL\Exception\NeedPrivileges</s:exception>
+  <s:message>User did not have the required privileges ({DAV:}read) for path "public-files/GbgdLgcoqYv8RF5"</s:message>
+  <d:need-privileges>
+    <d:resource>
+      <d:href>/remote.php/dav/public-files/GbgdLgcoqYv8RF5</d:href>
+      <d:privilege>
+        <d:read/>
+      </d:privilege>
+    </d:resource>
+  </d:need-privileges>
+</d:error>

modules/developer_manual/examples/core/webdav_api/public_files/response/public-link-is-available.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<d:multistatus xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:s="http://sabredav.org/ns">
+  <d:response>
+    <d:href>/remote.php/dav/public-files/GbgdLgcoqYv8RF5/</d:href>
+    <d:propstat>
+      <d:prop>
+        <d:resourcetype>
+          <d:collection/>
+        </d:resourcetype>
+      </d:prop>
+      <d:status>HTTP/1.1 200 OK</d:status>
+    </d:propstat>
+  </d:response>
+  <d:response>
+    <d:href>/remote.php/dav/public-files/GbgdLgcoqYv8RF5/welcome.txt</d:href>
+    <d:propstat>
+      <d:prop>
+        <d:getlastmodified>Mon, 30 Sep 2019 12:13:02 GMT</d:getlastmodified>
+        <d:getcontentlength>0</d:getcontentlength>
+        <d:resourcetype/>
+        <d:getetag>&quot;a28785e285ce0de0738676814705c4e1&quot;</d:getetag>
+        <d:getcontenttype>text/plain</d:getcontenttype>
+      </d:prop>
+      <d:status>HTTP/1.1 200 OK</d:status>
+    </d:propstat>
+    <d:propstat>
+      <d:prop>
+        <d:quota-used-bytes/>
+        <d:quota-available-bytes/>
+      </d:prop>
+      <d:status>HTTP/1.1 404 Not Found</d:status>
+    </d:propstat>
+  </d:response>
+</d:multistatus>
+

modules/developer_manual/nav.adoc

@@ -34,6 +34,7 @@
 ***** xref:webdav_api/search.adoc[The Search API]
 ***** xref:webdav_api/tags.adoc[The Tags API]
 ***** xref:webdav_api/trashbin.adoc[The Trash Bin API]
+***** xref:webdav_api/public_files.adoc[The Public Files API]
 ** xref:app/introduction.adoc[Application Development]
 *** xref:app/fundamentals/index.adoc[Fundamental Concepts]
 **** xref:app/fundamentals/info.adoc[Application Metadata]

modules/developer_manual/pages/webdav_api/public_files.adoc

@@ -0,0 +1,87 @@
+= Public Files API
+:toc: right
+:toclevels: 1
+:request-base-path: remote.php/dav/public-files
+:xmlpp-url: https://linux.die.net/man/1/xml_pp
+
+
+== Introduction
+
+The public-files API allows access to public links via WebDAV.
+
+[cols="40%,30%,30%",options="header",]
+|===
+| Request Path 
+| Method 
+| Content Type
+
+| `remote.php/dav/public-files/<share_token>` 
+| `PROPFIND` 
+| `text/xml`
+|===
+
+== Request Parameters
+
+[cols=",,",options="header",]
+|===
+|Attribute 
+|Type 
+|Description
+
+|`SHARE_TOKEN` 
+|string 
+|The share token for the public link.
+|===
+
+== Code Example
+
+[tabs]
+====
+Curl::
++
+--
+[source,console,subs="attributes+"]
+----
+include::{examplesdir}core/scripts/curl/dav/public_files/view_public_link.sh[]
+----
+--
+PHP::
++
+--
+[source,console,subs="attributes+"]
+----
+include::{examplesdir}core/scripts/php/dav/public_files/view_public_link.php[]
+----
+--
+====
+
+NOTE: No user and password is required, by default. 
+In case the public link _is_ protected with a password, use `public` for the username and the share link password for the password.
+
+TIP: The curl example uses {xmlpp-url}[xml_pp] to pretty print the result. 
+
+== Returns
+
+
+=== Example Response
+
+If the public link is available, then output similar to the following will be displayed.
+
+[source,xml]
+----
+include::{examplesdir}core/webdav_api/public_files/response/public-link-is-available.xml[]
+----
+
+If the share token is missing or invalid, then you will see output similar to the following:
+
+[source,xml]
+----
+include::{examplesdir}core/webdav_api/public_files/response/listing-members-is-disabled.xml[]
+----
+
+If the user does not have read privileges on the public link, then they will see output similar to the following:
+
+[source,xml]
+----
+include::{examplesdir}core/webdav_api/public_files/response/listing-members-is-disabled.xml[]
+----