OCS Share API
Introduction
The OCS Share API allows you to access the sharing API from outside over pre-defined OCS calls.
The base URL for all calls to the share API is: /ocs/v1.php/apps/files_sharing/api/v1/shares
.
Local Shares
Get All Shares
Get all shares shared with a user.
Endpoint |
|
Method |
GET |
Request Attributes
Attribute | Type | Description | ||||
---|---|---|---|---|---|---|
|
string |
sets the output format of the response.
Default value is |
||||
|
string |
limit the shares to those in a specific path. |
||||
|
boolean |
returns not only the shares shared with the current user but all shares. |
||||
|
string |
limits the returned shares to only those shared with the authenticating user. |
||||
|
string |
limits the returned shares to only those with the specified state.
Available options are
|
||||
|
boolean |
returns all shares within a folder, given that path defines a folder. This option requires the path option to be specified. |
Status Codes
Code | Description |
---|---|
100 |
Successful. |
400 |
Not a directory (if the `subfile' argument was used). |
404 |
Couldn’t fetch shares or file doesn’t exist. |
997 |
Unauthorised. |
Example Request Response Payloads
If the user that you’re connecting with is not authorized, then you will see output similar to the following:
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>997</statuscode>
<message>Unauthorised</message>
</meta>
<data/>
</ocs>
If the user that you’re connecting with is authorized, then you will see output similar to the following:
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data/>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>404</statuscode>
<message>wrong path, file/folder doesn't exist</message>
</meta>
<data/>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<element>
<id>115468</id>
<share_type>3</share_type>
<uid_owner>auser</uid_owner>
<displayname_owner>A User</displayname_owner>
<permissions>1</permissions>
<stime>1481537775</stime>
<parent/>
<expiration/>
<token>MMqyHrR0GTepo4B</token>
<uid_file_owner>auser</uid_file_owner>
<displayname_file_owner>A User</displayname_file_owner>
<path>/Photos/Paris.jpg</path>
<item_type>file</item_type>
<mimetype>image/jpeg</mimetype>
<storage_id>home::auser</storage_id>
<storage>993</storage>
<item_source>3994486</item_source>
<file_source>3994486</file_source>
<file_parent>3994485</file_parent>
<file_target>/Shared/Paris.jpg</file_target>
<share_with/>
<share_with_displayname/>
<url>https://your.owncloud.install.com/owncloud/index.php/s/MMqyHrR0GTepo4B</url>
<mail_send>0</mail_send>
</element>
</data>
</ocs>
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": null,
"totalitems": "",
"itemsperpage": ""
},
"data": [
{
"id": "1",
"share_type": 0,
"uid_owner": "testuser",
"displayname_owner": "test user",
"permissions": 19,
"stime": 1564484858,
"parent": null,
"expiration": null,
"token": null,
"uid_file_owner": "testuser",
"displayname_file_owner": "test user",
"state": 1,
"path": "/ownCloud Manual.pdf",
"item_type": "file",
"mimetype": "application/pdf",
"storage_id": "home::testuser",
"storage": 3,
"item_source": 97,
"file_source": 97,
"file_parent": 57,
"file_target": "/ownCloud Manual.pdf",
"share_with": "admin",
"share_with_displayname": "admin",
"share_with_additional_info": null,
"mail_send": 0,
"attributes": null
}
]
}
}
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1
curl --user username:password \
"$base_uri/$API_PATH/shares?path=/Photos/Paris.jpg&reshares=true"
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->get('shares?path=/Photos/Paris.jpg&reshares=true', [
'auth' => ['your.username', 'your.password'],
'debug' => true,
]);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares?path=/Photos/Paris.jpg&reshares=true")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Get.new uri
req.basic_auth 'your.username', 'your.password'
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
)
func main() {
base_uri := "https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
username := "your.username"
passwd := "your.password"
client := &http.Client{}
req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", base_uri, "shares"), nil)
if err != nil {
log.Print(err)
os.Exit(1)
}
// Add on some, relevant, query parameters
q := req.URL.Query()
q.Add("path", "/Photos/Paris.jpg")
q.Add("reshares", "true")
req.URL.RawQuery = q.Encode()
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
Get Information About A Known Share
Endpoint |
|
Method |
GET |
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1
curl --user username:password \
"$base_uri/$API_PATH/shares/115464"
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->get('shares/115464', [
'auth' => ['your.username', 'your.password'],
'debug' => true,
]);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares/115464")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Get.new uri
req.basic_auth 'your.username', 'your.password'
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
)
func main() {
base_uri := "https://owncloud.install.com/owncloudocs/v1.php/apps/files_sharing/api/v1"
username := "your.username"
passwd := "your.password"
client := &http.Client{}
req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", base_uri, "shares/115464"), nil)
if err != nil {
log.Print(err)
os.Exit(1)
}
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
package main
import okhttp3.Credentials
import okhttp3.OkHttpClient
import okhttp3.Request
import java.io.IOException
fun main(args: Array<String>) {
val ownCloudDomain = "https://owncloud.install.com/owncloud"
var client = OkHttpClient()
val credentials = Credentials.basic("your.username", "your.password");
var builder = Request.Builder()
.url("$ownCloudDomain/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>'")
.header("Authorization", credentials)
.build()
try {
var response = client.newCall(builder).execute()
when {
response.isSuccessful -> println(
"Request was successful. Response was: ${response.body()?.string()}"
)
else -> println("Request was not successful.")
}
} catch (e: IOException) {
println("Request failed. Reason: ${e.toString()}")
}
}
import okhttp3.Credentials;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
public class GetShareInfo {
OkHttpClient client = new OkHttpClient();
String run(String url, String credentials) throws IOException {
Request request = new Request.Builder()
.url(url)
.header("Authorization", credentials)
.build();
try (Response response = client.newCall(request).execute()) {
if (response.isSuccessful()) {
String responseBody = (response.body().string() != null) ? response.body().string() : "empty";
return "Request was successful. Response was: " + responseBody;
}
} catch (IOException e) {
return "Request was not successful. Reason: " + e.toString();
}
return "Request was not successful.";
}
public static void main(String[] args) throws IOException {
GetShareInfo info = new GetShareInfo();
String credentials = Credentials.basic("your.username", "your.password");
String ownCloudDomain = "https://owncloud.install.com/owncloud";
String url = ownCloudDomain + "/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>'";
String response = info.run(url, credentials);
System.out.println(response);
}
}
The Java and Kotlin examples use the square/okhttp library. |
Example Response Payloads
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<element>
<id>115464</id>
<share_type>6</share_type>
<uid_owner>auser</uid_owner>
<displayname_owner>A User</displayname_owner>
<permissions>3</permissions>
<stime>1481535991</stime>
<parent/>
<expiration/>
<token>l5h8JYPb455oFkv</token>
<uid_file_owner>auser</uid_file_owner>
<displayname_file_owner>A User</displayname_file_owner>
<path>/ownCloud Manual.pdf</path>
<item_type>file</item_type>
<mimetype>application/pdf</mimetype>
<storage_id>home::auser</storage_id>
<storage>993</storage>
<item_source>3994491</item_source>
<file_source>3994491</file_source>
<file_parent>3994484</file_parent>
<file_target></file_target>
<share_with>user@example.com</share_with>
<share_with_displayname>user@example.com</share_with_displayname>
<name>ownCloud Manual</name>
<mail_send>0</mail_send>
</element>
</data>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>404</statuscode>
<message>wrong share ID, share doesn't exist.</message>
</meta>
<data/>
</ocs>
Response Attributes
For details about the elements in the XML response payload please refer to the Response Attributes section of the Create a New Share section below.
Accept a Pending Share
Endpoint |
|
Method |
POST |
Request Attributes
Attribute | Type | Description |
---|---|---|
share id |
integer |
the id of the pending share to accept. Pending share ids are available in the get all shares response. |
Example Request Response Payloads
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data>
<element>
<id>1</id>
<share_type>0</share_type>
<uid_owner>testuser</uid_owner>
<displayname_owner>test user</displayname_owner>
<permissions>19</permissions>
<stime>1564484858</stime>
<parent/>
<expiration/>
<token/>
<uid_file_owner>testuser</uid_file_owner>
<displayname_file_owner>test user</displayname_file_owner>
<state>0</state>
<path>/ownCloud Manual.pdf</path>
<item_type>file</item_type>
<mimetype>application/pdf</mimetype>
<storage_id>shared::/ownCloud Manual.pdf</storage_id>
<storage>3</storage>
<item_source>97</item_source>
<file_source>97</file_source>
<file_parent>6</file_parent>
<file_target>/ownCloud Manual.pdf</file_target>
<share_with>admin</share_with>
<share_with_displayname>admin</share_with_displayname>
<share_with_additional_info/>
<mail_send>0</mail_send>
<attributes/>
</element>
</data>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>404</statuscode>
<message>Wrong share ID, share doesn't exist</message>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data/>
</ocs>
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1
curl -X POST \
--user username:password \
"$base_uri/$API_PATH/shares/pending/<share_id>"
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->request(
'POST',
'shares/pending/1',
[
'auth' => ['username', 'password'],
'debug' => true,
]
);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares/pending/1")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Post.new uri
req.basic_auth 'username', 'password'
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
)
func main() {
base_uri := "https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
username := "username"
passwd := "password"
client := &http.Client{}
req, err := http.NewRequest("POST", fmt.Sprintf("%s/%s", base_uri, "shares/pending/<share_id>"), nil)
if err != nil {
log.Print(err)
os.Exit(1)
}
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
Decline a Pending Share
Endpoint |
|
Method |
DELETE |
Request Attributes
Attribute | Type | Description |
---|---|---|
share id |
integer |
the id of the pending share to decline. Pending share ids are available in the get all shares response. |
Status Codes
Code | Description |
---|---|
200 |
|
Example Request Response Payloads
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data/>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>404</statuscode>
<message>Wrong share ID, share doesn't exist</message>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data/>
</ocs>
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1
curl -X DELETE \
--user username:password \
"$base_uri/$API_PATH/shares/pending/<share_id>"
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->request(
'DELETE',
'shares/pending/<share_id>',
[
'auth' => ['username', 'password'],
'debug' => true,
]
);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares/pending/<share_id>")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Delete.new uri
req.basic_auth 'your.username', 'your.password'
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"os"
)
func main() {
base_uri := "https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
username := "admin"
passwd := "admin"
client := &http.Client{}
req, err := http.NewRequest("DELETE", fmt.Sprintf("%s/%s", base_uri, "shares/pending/<share_id>"), nil)
if err != nil {
log.Print(err)
os.Exit(1)
}
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
Create A New Share
Share an existing file or folder with a user, a group, or as a public link.
Endpoint |
|
Method |
POST |
Function Arguments
Argument | Type | Description |
---|---|---|
name |
string |
A (human-readable) name for the share, which can be up to 64 characters in length. |
path |
string |
The path to the file or folder which should be shared. |
shareType |
int |
The type of the share. This can be one of:
|
shareWith |
string |
The user or group id with which the file should be shared. |
publicUpload |
boolean |
Whether to allow public upload to a public link shared folder. |
password |
string |
The password to protect the public link share with. |
permissions |
int |
The permissions to set on the share.
|
expireDate |
string |
An expire date for the user, group or public link share.
This argument expects a date string in the following format |
attributes |
array |
Contain a set of one or more permissions to set for a share. The list of available permissions can be obtained from a request to the Roles API. |
Things to remember about public link shares
Mandatory Fields
|
Status Codes
Code | Description |
---|---|
100 |
Successful |
400 |
Unknown share type |
403 |
Public upload was disabled by the admin |
404 |
File or folder couldn’t be shared |
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1/shares
# Create a public link share of a single file with read permissions, named "paris photo"
curl --user username:password "$base_uri/$API_PATH" \
--data 'path=/Photos/Paris.jpg&shareType=3&permissions=3&name=paris%20photo'
# Create a public link share of a single file with read and write permissions, named "Notes"
curl --user username:password "$base_uri/$API_PATH" \
--data 'path=/Documents/notes.txt&shareType=3&permissions=15&name=Notes'
# Create a user share with read permissions, named "welcome.txt" that has read
# and share permissions set.
curl --silent --user username:password \
"$base_uri/$API_PATH/" \
--data 'path=/welcome.txt' \
--data 'shareType=3' \
--data 'name=welcome.txt' \
--data 'attributes[0][scope]=ownCloud&attributes[0][key]=read&attributes[0][value]=true'
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->post('shares', [
'auth' => ['your.username', 'your.password'],
'debug' => true,
'form_params' => [
'path' => 'Photos/Paris.jpg',
'shareType' => 3,
'permissions' => 1
]
]);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Get.new uri
req.basic_auth 'your.username', 'your.password'
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"strconv"
"strings"
)
func main() {
base_uri := "https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
username := "your.username"
passwd := "your.password"
client := &http.Client{}
// Set the form POST body
form := url.Values{}
form.Add("path", "/Photos/Paris.jpg")
form.Add("shareType", "3")
form.Add("permissions", "1")
// Build the core request object
req, _ := http.NewRequest(
"POST",
fmt.Sprintf("%s/%s", base_uri, "shares"),
strings.NewReader(form.Encode()),
)
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
req.Header.Add("Content-Length", strconv.Itoa(len(form.Encode())))
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
Example Request Response Payloads
Failure
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>400</statuscode>
<message>unknown share type</message>
</meta>
<data/>
</ocs>
Success
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<id>115468</id>
<share_type>3</share_type>
<uid_owner>auser</uid_owner>
<displayname_owner>A User</displayname_owner>
<permissions>1</permissions>
<stime>1481537775</stime>
<parent/>
<expiration/>
<token>MMqyHrR0GTepo4B</token>
<uid_file_owner>auser</uid_file_owner>
<displayname_file_owner>A User</displayname_file_owner>
<path>/Photos/Paris.jpg</path>
<item_type>file</item_type>
<mimetype>image/jpeg</mimetype>
<storage_id>home::auser</storage_id>
<storage>993</storage>
<item_source>3994486</item_source>
<file_source>3994486</file_source>
<file_parent>3994485</file_parent>
<file_target>/Shared/Paris.jpg</file_target>
<share_with/>
<share_with_displayname/>
<url>https://your.owncloud.install.com/owncloud/index.php/s/MMqyHrR0GTepo4B</url>
<mail_send>0</mail_send>
<name>paris photo</name>
</data>
</ocs>
Response Attributes
Argument | Type | Description |
---|---|---|
id |
int |
The share’s unique id. |
share_type |
int |
The share’s type. This can be one of:
|
uid_owner |
string |
The username of the owner of the share. |
displayname_owner |
string |
The display name of the owner of the share. |
permissions |
octal a |
The permission attribute set on the file. Options are: * 1 = Read * 2 = Update * 4 = Create * 8 = Delete * 16 = Share * 31 = All permissions The default is 31, and for public link shares is 1. |
stime |
int |
The UNIX timestamp when the share was created. |
parent |
int |
The UNIX timestamp when the share was created. |
expiration |
string |
The date when the share expires, in format YYYY-MM-DD 00:00:00. |
token |
string |
The public link to the item being shared. |
uid_file_owner |
string |
The unique id of the user that owns the file or folder being shared. |
displayname_file_owner |
string |
The display name of the user that owns the file or folder being shared. |
path |
string |
The path to the shared file or folder. |
item_type |
string |
The type of the object being shared. This can be one of file or folder. |
mimetype |
string |
The RFC-compliant mimetype of the file. |
storage_id |
string |
|
storage |
int |
|
item_source |
int |
The unique node id of the item being shared. |
file_source |
int |
The unique node id of the item being shared. For legacy reasons item_source and file_source attributes have the same value. |
file_parent |
int |
The unique node id of the parent node of the item being shared. |
file_target |
int |
The name of the shared file. |
share_with |
string |
The uid of the receiver of the file. This is either a GID (group id) if it is being shared with a group or a UID (user id) if the share is shared with a user. |
share_with_displayname |
string |
The display name of the receiver of the file. |
url |
string |
|
mail_send |
int |
Whether the recipient was notified, by mail, about the share being shared with them. |
name |
string |
A (human-readable) name for the share, which can be up to 64 characters in length |
Delete A Share
Remove the given share.
Endpoint |
|
Method |
DELETE |
Attribute | Type | Description |
---|---|---|
share_id |
int |
The share’s unique id |
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1
curl --user username:password \
"$base_uri/$API_PATH/shares/115470" \
--request DELETE
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->delete('shares/115468', [
'auth' => ['your.username', 'your.password'],
'debug' => true,
]);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares/115468")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Delete.new uri
req.basic_auth 'your.username', 'your.password'
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
)
func main() {
base_uri := "https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
username := "your.username"
passwd := "your.password"
client := &http.Client{}
// Build the core request object
req, _ := http.NewRequest(
"DELETE",
fmt.Sprintf("%s/%s", base_uri, "shares/115470"),
nil,
)
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
Example Request Response Payloads
Failure
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data/>
</ocs>
Success
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>404</statuscode>
<message>wrong share ID, share doesn't exist.</message>
</meta>
<data/>
</ocs>
Update Share
Update a given share. Only one value can be updated per request.
Endpoint |
|
Method |
Request Arguments
Argument | Type | Description |
---|---|---|
name |
string |
A (human-readable) name for the share, which can |
be up to 64 characters in length |
||
share_id |
int |
The share’s unique id |
permissions |
int |
Update permissions |
(see the create share section above) |
||
password |
string |
Updated password for a public link share |
publicUpload |
boolean |
Enable (true) / disable (false) |
public upload for public link shares. |
||
expireDate |
string |
Set an expire date for the user, group or public link share. |
This argument expects a well-formatted date string, |
||
such as: `YYYY-MM-DD' |
Only one of the update parameters can be specified at once. |
Status Codes
Code | Description |
---|---|
100 |
Successful |
400 |
Wrong or no update parameter given |
403 |
Public upload disabled by the admin |
404 |
Couldn’t update share |
Code Example
#!/bin/bash
##
## Variable Declaration
##
base_uri=https://owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1
curl --user username:password \
"$base_uri/$API_PATH/shares/115470" \
--request PUT \
--data 'expireDate=2017-01-02&name=paris%20photo'
<?php
use GuzzleHttp\Client;
require_once ('vendor/autoload.php');
// Configure the basic client
$client = new Client([
'base_uri' => 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);
try {
$response = $client->put('shares/115470', [
'auth' => ['your.username', 'your.password'],
'debug' => true,
'form_params' => [
'expireDate' => '2017-01-01'
]
]);
print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
print $e->getMessage();
}
require 'net/http'
require 'uri'
base_uri = 'https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI(base_uri + "shares/115470")
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
req = Net::HTTP::Put.new uri
req.basic_auth 'your.username', 'your.password'
req.set_form_data('expireDate' => '2017-01-03')
res = http.request req
puts res.body
end
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
"strconv"
"strings"
)
func main() {
base_uri := "https://owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
username := "your.username"
passwd := "your.password"
client := &http.Client{}
// Set the form POST body
form := url.Values{}
form.Add("expireDate", "2017-01-03")
// Build the core request object
req, _ := http.NewRequest(
"PUT",
fmt.Sprintf("%s/%s", base_uri, "shares/115470"),
strings.NewReader(form.Encode()),
)
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
req.Header.Add("Content-Length", strconv.Itoa(len(form.Encode())))
req.SetBasicAuth(username, passwd)
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
bodyText, err := ioutil.ReadAll(resp.Body)
fmt.Println(string(bodyText))
}
Example Request Response Payloads
Failure
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>400</statuscode>
<message>can't change permission for public link share</message>
</meta>
<data/>
</ocs>
Success
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<id>115470</id>
<share_type>3</share_type>
<uid_owner>auser</uid_owner>
<displayname_owner>A User</displayname_owner>
<permissions>1</permissions>
<stime>1481552410</stime>
<parent/>
<expiration>2017-01-01 00:00:00</expiration>
<token>11CUiVe0l7iaIwM</token>
<uid_file_owner>auser</uid_file_owner>
<displayname_file_owner>A User</displayname_file_owner>
<path>/Photos/Paris.jpg</path>
<item_type>file</item_type>
<mimetype>image/jpeg</mimetype>
<storage_id>home::auser</storage_id>
<storage>993</storage>
<item_source>3994486</item_source>
<file_source>3994486</file_source>
<file_parent>3994485</file_parent>
<file_target>/Shared/Paris.jpg</file_target>
<share_with/>
<share_with_displayname/>
<url>https://your.owncloud.install.com/owncloud/index.php/s/11CUiVe0l7iaIwM</url>
<mail_send>0</mail_send>
<name>paris photo</name>
</data>
</ocs>
Federated Cloud Shares
Both the sending and the receiving instance need to have federated cloud sharing enabled and configured. See Configuring Federated Cloud Sharing.
Create A New Federated Cloud Share
Creating a federated cloud share can be done via the local share endpoint, using (int) 6 as a shareType and the Federated Cloud ID of the share recipient as shareWith. See Create a new Share for more information.
List Accepted Federated Cloud Shares
Get all federated cloud shares the user has accepted.
-
Syntax: /remote_shares
-
Method: GET
Get Information About A Known Federated Cloud Share
Get information about a given received federated cloud share that was sent from a remote instance.
-
Syntax: /remote_shares/<share_id>
-
Method: GET
Attribute | Type | Description |
---|---|---|
share_id |
int |
The share id as listed in the id field |
in the |
Delete An Accepted Federated Cloud Share
Locally delete a received federated cloud share that was sent from a remote instance.
-
Syntax: /remote_shares/<share_id>
-
Method: DELETE
Attribute | Type | Description |
---|---|---|
share_id |
int |
The share id as listed in the id field |
in the |
List Pending Federated Cloud Shares
Get all pending federated cloud shares the user has received.
-
Syntax: /remote_shares/pending
-
Method: GET
Accept a Pending Federated Cloud Share
Locally accept a received federated cloud share that was sent from a remote instance.
-
Syntax: /remote_shares/pending/<share_id>
-
Method: POST
Attribute | Type | Description |
---|---|---|
share_id |
int |
The share id as listed in the id field |
in the |