Playing with the new ownCloud share API

I use OwnCloud since v2, and really enjoy it, mainly since desktop clients are available. I can easily sync a file if I copy it in my ~/ownCloud/ directory (dropbox style) !

But one of the missing feature for me is a share API. You can synchronize files from your desktop client or owncloud smartphone apps, but you CAN’T share a file without going to the web interface… Pretty annoying. I need this feature to quickly share a file with a public URL (share on IRC or IM)

Since owncloud v6 ( ~~still in beta stage ATM~~ Now released !), a share api is now available!

The documentation is available here on the owncloud github account. So let’s try ! (Note: it only works on owncloud 6 !)

It’s a REST API, so you can use it simply via cURL call. Here are some examples.

Get all shares for your user ( you need your session cookie to be authenticated during requests):

Request :

curl "https://your.instance.com/ocs/v1.php/apps/files_sharing/api/v1/shares" -k -H 'Cookie: ocxxxxx=xxxxxxxxx'

Response :

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message/>
 </meta>
 <data>
  <element>
   <id>1</id>
   <item_type>file</item_type>
   <parent/>
   <share_type>3</share_type>
   <share_with/>
   <file_source>6</file_source>
   <path>/ownCloudUserManual.pdf</path>
   <permissions>1</permissions>
   <stime>1383432712</stime>
   <expiration/>
   <token>yyyyyyyyyyyyyyyyyyyyyy</token>
   <storage>1</storage>
   <mail_send>0</mail_send>
  </element>
  <element>
   <id>2</id>
   <item_type>folder</item_type>
   <parent/>
   <share_type>3</share_type>
   <share_with/>
   <file_source>5</file_source>
   <path>/photos</path>
   <permissions>1</permissions>
   <stime>1383434668</stime>
   <expiration/>
   <token>31ca68aae4d357cf6c89598983cd0c25</token>
   <storage>1</storage>
   <mail_send>0</mail_send>
  </element>
 </data>
</ocs>

Create a public share (type 3) for “Pictures/picture1.png”

Request :

curl "https://your.instance.com/ocs/v1.php/apps/files_sharing/api/v1/shares" -k -u $USER:$PASS -X POST --data "path=Pictures/picture1.png&shareType=3"

Response :

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message/>
 </meta>
 <data>
  <id>1</id>
  <url>https://your.instance.com/public.php?service=files&amp;t=xxxxxxxxxxxxxxxxxxxxxxxxxxx</url>
  <token>yyyyyyyyyyyyyyyy</token>
 </data>
</ocs>

File is now available publicy to https://your.instance.com/public.php?service=files&t=xxxxxxxxxxxxxxxxxxxxxxxxxxx !

So, you can use a simple shell script to share a file automagically and copy the public URL to your clipboard. You need bash, xclip and xpath (perl-xml-xpath -ArchLinux- or libxml-xpath-perl -Debian-).

Update 2014/03/01 : A public link creator script is now available on http://blog.schiessle.org/2013/12/30/the-owncloud-public-link-creator/ :)

#!/bin/bash
# This is a quick & dirty shell script, consider it as a proof of concept ;) 
# License: WTFPL v2 
# Author: Skunnyk{@}alteroot.org
# Change theses 3 values
url="https://your.instance.com"
user="User"
pass="Password"
# You should not touch theses values
curlopts="-s -k"
apiurl="ocs/v1.php/apps/files_sharing/api/v1/shares"

# Some checks
for executables in xpath curl xclip; do
    command -v $executables  >/dev/null 2>&1 || { echo >&2 "I need $executables but it's not installed."; exit 1; }
done

usage() {
    echo ""
    echo ""
    echo "USAGE : "
    echo "$(basename $0) path/to/file"
    echo "Don't forget to change url/user/pass variables in this script"
    echo ""
}

if [[ $# -ne 1 ]]; then
    usage
    exit 1
fi

file="$1"

command="curl $curlopts $url/$apiurl -u $user:$pass -X POST --data path=$1&shareType=3"

result=$($command | xpath "/ocs/data/url/text()" 2>/dev/null)
if [ -z $result ]; then
    echo "Error on share..." 
    exit 1
else
    echo $result | sed "s/amp;//" | xclip
    xclip -o
fi

Now, you juste need to launch “share-me.sh MyDocument” or “share-me.sh photos/photo.png”, and the public share URL will be copied to your clipboard.

I hope this feature will be added soon in the desktop and android/ios client :)

Enjoy,