Roles API

Table of Contents

Introduction

The roles API allows clients to ask the server for supported roles. Three things are worth noting about this API:

  1. Only roles for public links are implemented.

  2. Apps can listen to the event dispatcher and add their own roles.

  3. Apps cannot change existing roles.

Get Roles

Request Path Method Content Type

ocs/v1.php/cloud/roles

GET

text/xml or text/json

Request Parameters

Attribute Type Description

format

string

The format of the response content. Accepted values are xml and json.

Code Example

  • Curl

#!/usr/bin/env bash

API_PATH="ocs/v1.php/cloud/roles?format=json"
SERVER_URI="https://owncloud.install.com/owncloud"

curl '$SERVER_URI/$API_PATH/' \
  --user "username:password" | jq

Returns

On success, the request returns either an XML (the default) or a JSON response body, along with an HTTP 200 OK status code. The response body lists all the available roles, along with information about each one.

Example Responses

  • JSON

  • XML

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 100,
      "message": "OK",
      "totalitems": "",
      "itemsperpage": ""
    },
    "data": [
      {
        "id": "core.viewer",
        "displayName": "Download / View",
        "context": {
          "publicLinks": {
            "displayDescription": "Recipients can view or download contents.",
            "order": 10,
            "resourceTypes": [
              "*"
            ],
            "permissions": {
              "ownCloud": {
                "read": true
              }
            }
          }
        }
      },
      {
        "id": "core.contributor",
        "displayName": "Download / View / Upload",
        "context": {
          "publicLinks": {
            "displayDescription": "Recipients can view, download and upload contents.",
            "order": 20,
            "resourceTypes": [
              "httpd/unix-directory"
            ],
            "permissions": {
              "ownCloud": {
                "create": true,
                "read": true
              }
            }
          }
        }
      },
      {
        "id": "core.editor",
        "displayName": "Download / View / Edit",
        "context": {
          "publicLinks": {
            "displayDescription": "Recipients can view, download, edit, delete and upload contents.",
            "order": 30,
            "resourceTypes": [
              "httpd/unix-directory"
            ],
            "permissions": {
              "ownCloud": {
                "create": true,
                "read": true,
                "update": true,
                "delete": true
              }
            }
          }
        }
      },
      {
        "id": "core.uploader",
        "displayName": "Upload only (File Drop)",
        "context": {
          "publicLinks": {
            "displayDescription": "Receive files from multiple recipients without revealing the contents of the folder.",
            "order": 40,
            "resourceTypes": [
              "httpd/unix-directory"
            ],
            "permissions": {
              "ownCloud": {
                "create": true
              }
            }
          }
        }
      }
    ]
  }
}
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message>OK</message>
  <totalitems></totalitems>
  <itemsperpage></itemsperpage>
 </meta>
 <data>
  <element>
   <id>core.viewer</id>
   <displayName>Download / View</displayName>
   <context>
    <publicLinks>
     <displayDescription>Recipients can view or download contents.</displayDescription>
     <order>10</order>
     <resourceTypes>
      <element>*</element>
     </resourceTypes>
     <permissions>
      <ownCloud>
       <read>1</read>
      </ownCloud>
     </permissions>
    </publicLinks>
   </context>
  </element>
  <element>
   <id>core.contributor</id>
   <displayName>Download / View / Upload</displayName>
   <context>
    <publicLinks>
     <displayDescription>Recipients can view, download and upload contents.</displayDescription>
     <order>20</order>
     <resourceTypes>
      <element>httpd/unix-directory</element>
     </resourceTypes>
     <permissions>
      <ownCloud>
       <create>1</create>
       <read>1</read>
      </ownCloud>
     </permissions>
    </publicLinks>
   </context>
  </element>
  <element>
   <id>core.editor</id>
   <displayName>Download / View / Edit</displayName>
   <context>
    <publicLinks>
     <displayDescription>Recipients can view, download, edit, delete and upload contents.</displayDescription>
     <order>30</order>
     <resourceTypes>
      <element>httpd/unix-directory</element>
     </resourceTypes>
     <permissions>
      <ownCloud>
       <create>1</create>
       <read>1</read>
       <update>1</update>
       <delete>1</delete>
      </ownCloud>
     </permissions>
    </publicLinks>
   </context>
  </element>
  <element>
   <id>core.uploader</id>
   <displayName>Upload only (File Drop)</displayName>
   <context>
    <publicLinks>
     <displayDescription>Receive files from multiple recipients without revealing the contents of the folder.</displayDescription>
     <order>40</order>
     <resourceTypes>
      <element>httpd/unix-directory</element>
     </resourceTypes>
     <permissions>
      <ownCloud>
       <create>1</create>
      </ownCloud>
     </permissions>
    </publicLinks>
   </context>
  </element>
 </data>
</ocs>

Setting The Language of the Response Body

The language of the response’s content can be set with the Accept-Language header. By default, the response will be in English. You can see an example of requesting the response in a specific language in the code example below.

  • Curl

#!/usr/bin/env bash

API_PATH="ocs/v1.php/cloud/roles?format=json"
SERVER_URI="https://owncloud.install.com/owncloud"

curl '$SERVER_URI/$API_PATH/' \
  --user "username:password" \
  -H 'Accept-Language: de-DE' | jq