From 32850dbb861446b41ba73d366bc910bce3e8fc2c Mon Sep 17 00:00:00 2001 From: Carla Schroder Date: Wed, 21 Jan 2015 15:21:56 -0800 Subject: [PATCH] Add provisioning_api doc to Server manual (formerly EE only) --- admin_manual/configuration/index.rst | 1 + .../configuration/user_provisioning_api.rst | 795 ++++++++++++++++++ admin_manual/index.rst | 1 + 3 files changed, 797 insertions(+) create mode 100644 admin_manual/configuration/user_provisioning_api.rst diff --git a/admin_manual/configuration/index.rst b/admin_manual/configuration/index.rst index 8435b39b3..e99307acb 100644 --- a/admin_manual/configuration/index.rst +++ b/admin_manual/configuration/index.rst @@ -33,4 +33,5 @@ Configuration user_auth_ftp_smb_imap user_auth_ldap user_configuration + user_provisioning_api reset_admin_password \ No newline at end of file diff --git a/admin_manual/configuration/user_provisioning_api.rst b/admin_manual/configuration/user_provisioning_api.rst new file mode 100644 index 000000000..5f716a63f --- /dev/null +++ b/admin_manual/configuration/user_provisioning_api.rst @@ -0,0 +1,795 @@ +===================== +User Provisioning API +===================== + +The Provisioning API application is exclusive to ownCloud Enterprise Edition, +and is enabled by default. + +This application enables a set of APIs that external systems can use to create, +edit, delete and query user attributes, query, set and remove groups, set quota +and query total storage used in ownCloud. Group admin users can also query +ownCloud and perform the same functions as an admin for groups they manage. The +API also enables an admin to query for active ownCloud applications, application +info, and to enable or disable an app remotely. Once the app is enabled, HTTP +requests can be used via a Basic Auth header to perform any of the functions +listed above. + +The base URL for all calls to the share API is **/ocs/v1.php/cloud**. + +Instruction set +=============== + +users / adduser +=============== + +Create a new user on the ownCloud server. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v1.php/cloud/users** + +* HTTP method: POST +* POST argument: userid - string, the required username for the new user +* POST argument: password - string, the required password for the new user + +Status codes: + +* 100 - successful +* 101 - invalid input data +* 102 - username already exists +* 103 - unknown error occurred whilst adding the user + +Example +------- + +* POST ``http://admin:secret@example.com/ocs/v1.php/cloud/users -d user="Frank" -d + password="frankspassword"`` +* Creates the user ``Frank`` with password ``frankspassword`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + frank@example.org + 0 + true + + + +users / getusers +================ + +Retrieves a list of users from the cloud server. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users** + +* HTTP method: GET +* url arguments: search - string, optional search string +* url arguments: limit - int, optional limit value +* url arguments: offset - int, optional offset value + +Status codes: + +* 100 - successful + +Example +------- + +* GET ``http://admin:secret@example.com/ocs/v1.php/cloud/users?search=Frank`` +* Returns list of users matching the search string. + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + Frank + + + + +users / getuser +=============== + +Retrieves information about a single user. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}** + +* HTTP method: GET + +Status codes: + +* 100 - successful + +Example +------- + + * GET ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank`` + * Returns information on the user ``Frank`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + frank@example.org + 0 + true + + + +users / edituser +================ + +Edits attributes related to a user. Users are able to edit email, displayname and password; admins can also edit the quota value. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}** + +* HTTP method: PUT +* PUT argument: key, the field to edit (email, quota, displayname, password) +* PUT argument: value, the new value for the field + +Status codes: + +* 100 - successful +* 101 - user not found +* 102 - invalid input data + +Example +------- + + * PUT ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d key="email", + value="franksnewemail@example.org"`` + * Updates the email address for the user ``Frank`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +users / deleteuser +================== + +Deletes a user from the cloud server. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}** + +* HTTP method: DELETE + +Statuscodes: + +* 100 - successful +* 101 - failure + +Example +------- + + * DELETE ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank`` + * Deletes the use ``Frank`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +users / getgroups +================= + +Retrieves a list of groups the specified user is a member of. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}/groups** + +* HTTP method: GET + +Status codes: + +* 100 - successful + +Example +------- + + * GET ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups`` + * Retrieves a list of groups of which ``Frank`` is a member + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + admin + group1 + + + + +users / addtogroup +================== + +Adds the specified user to the specified group. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}/groups** + +* HTTP method: POST +* POST argument: groupid, string - the group to add the user to + +Status codes: + +* 100 - successful +* 101 - no group specified +* 102 - group does not exist +* 103 - user does not exist +* 104 - insufficient privileges +* 105 - failed to add user to group + +Example +------- + + * POST ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -d + groupid="newgroup"`` + * Adds the user ``Frank`` to the group ``newgroup`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +users / removefromgroup +======================= + +Removes the specified user from the specified group. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}/groups** + +* HTTP method: DELETE +* POST argument: groupid, string - the group to remove the user from + +Status codes: + +* 100 - successful +* 101 - no group specified +* 102 - group doesnt exist +* 103 - user doesn't exist +* 104 - insufficient privileges +* 105 - failed to remove user from group + +Example +------- + + * DELETE ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -d + groupid="newgroup"`` + * Removes the user ``Frank`` from the group ``newgroup`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +users / createsubadmin +====================== + +Makes a user the subadmin of a group. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins** + +* HTTP method: POST +* POST argument: groupid, string - the group of which to make the user a subadmin + +Status codes: + +* 100 - successful +* 101 - user does not exist +* 102 - group does not exist +* 103 - unkown failure + +Example +------- + + * POST ``http://admin:secret@myowncloud.org/ocs/v1.php/cloud/users/Frank/subadmin -d + groupid="group"`` + * Makes the user ``Frank`` a subadmin of the ``group`` group + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +users / removesubadmin +====================== + +Removes the subadmin rights for the user specified from the group specified. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}/subadmin** + +* HTTP method: DELETE +* DELETE argument: groupid, string - the group from which to remove the user's subadmin rights + +Status codes: + +* 100 - successful +* 101 - user does not exist +* 102 - user is not a subadmin of the group / group does not exist +* 103 - unknown failure + +Example +------- + + * DELETE ``http://admin:secret@myowncloud.org/ocs/v1.php/cloud/users/Frank/subadmin -d groupid="oldgroup"`` + * Removes ``Frank's`` subadmin rights from the ``oldgroup`` group + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +users / getsubadmingroups +========================= + +Returns the groups in which the user is a subadmin. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins** + +* HTTP method: GET + +Status codes: + +* 100 - successful +* 101 - user does not exist +* 102 - unkown failure + +Example +------- + + * GET ``http://admin:secret@myowncloud.org/ocs/v1.php/cloud/users/Frank/subadmin`` + * Returns the groups of which ``Frank`` is a subadmin + +XML Output +---------- + +.. code-block:: xml + + + + + ok + 100 + + + + testgroup + + + + +groups / getgroups +================== + +Retrieves a list of groups from the cloud server. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/groups** + +* HTTP method: GET +* url arguments: search - string, optional search string +* url arguments: limit - int, optional limit value +* url arguments: offset - int, optional offset value + +Status codes: + +* 100 - successful + +Example +------- + + * GET ``http://admin:secret@example.com/ocs/v1.php/cloud/groups?search=adm`` + * Returns list of groups matching the search string. + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + admin + + + + +groups / addgroup +================= + +Adds a new group. Authentication is done by +sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/groups** + +* HTTP method: POST +* POST argument: groupid, string - the new groups name + +Status codes: + +* 100 - successful +* 101 - invalid input data +* 102 - group already exists +* 103 - failed to add the group + +Example +------- + + * POST ``http://admin:secret@example.com/ocs/v1.php/cloud/groups -d groupid="newgroup"`` + * Adds a new group called ``newgroup`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +groups / getgroup +================= + +Retrieves a list of group members. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/groups/{groupid}** + +* HTTP method: GET + +Status codes: + +* 100 - successful + +Example +------- + + * POST ``http://admin:secret@example.com/ocs/v1.php/cloud/groups/admin`` + * Returns a list of users in the ``admin`` group + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + Frank + + + + +groups / getsubadmins +===================== + +Returns subadmins of the group. Authentication is done by +sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/groups/{groupid}/subadmins** + +* HTTP method: GET + +Status codes: + +* 100 - successful +* 101 - group doesn't exist +* 102 - unknown failure + +Example +------- + + * GET ``http://admin:secret@myowncloud.org/ocs/v1.php/cloud/groups/mygroup/subadmins`` + * Return the subadmins of the group: ``mygroup`` + +XML Output +---------- + +.. code-block:: xml + + + + + ok + 100 + + + + Tom + + + +groups / deletegroup +==================== + +Removes a group. Authentication is done by +sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/groups/{groupid}** + +* HTTP method: DELETE + +Status codes: + +* 100 - successful +* 101 - group doesn't exist +* 102 - failed to delete group + +Example +------- + + * DELETE ``http://admin:secret@example.com/ocs/v1.php/cloud/groups/mygroup`` + * Delete the group ``mygroup`` + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + +apps / getapps +============== + +Returns a list of apps installed on the cloud server. Authentication is done by sending a Basic HTTP Authorization +header. + +**Syntax: ocs/v1.php/cloud/apps/** + +* HTTP method: GET +* url argument: filter, string - optional (``enabled`` or ``disabled``) + +Status codes: + +* 100 - successful +* 101 - invalid input data + +Example +------- + + * GET ``http://admin:secret@example.com/ocs/v1.php/cloud/apps?filter=enabled`` + * Gets enabled apps + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + files + provisioning_api + + + + +apps / getappinfo +================= + +Provides information on a specific application. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/apps/{appid}** + +* HTTP method: GET + +Status codes: + +* 100 - successful + +Example +------- + + * GET ``http://admin:secret@example.com/ocs/v1.php/cloud/apps/files`` + * Get app info for the ``files`` app + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + + + appinfo/remote.php + appinfo/remote.php + appinfo/filesync.php + + + files + Files + File Management + AGPL + Robin Appelman + 4.9 + true + + + + filesystem + + + + +apps / enable +============= + +Enable an app. Authentication is done by sending a Basic HTTP Authorization header. + +**Syntax: ocs/v1.php/cloud/apps/{appid}** + +* HTTP method: POST + +Status codes: + +* 100 - successful + +Example +------- + + * POST ``http://admin:secret@example.com/ocs/v1.php/cloud/apps/files_texteditor`` + * Enable the ``files_texteditor`` app + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + +apps / disable +============== + +Disables the specified app. Authentication is +done by sending a Basic HTTP Authorization header. + + +**Syntax: ocs/v1.php/cloud/apps/{appid}** + +* HTTP method: DELETE + +Status codes: + +* 100 - successful + +Example +------- + + * DELETE ``http://admin:secret@example.com/ocs/v1.php/cloud/apps/files_texteditor`` + * Disable the ``files_texteditor`` app + +XML Output +---------- + +.. code-block:: xml + + + + + 100 + ok + + + \ No newline at end of file diff --git a/admin_manual/index.rst b/admin_manual/index.rst index 589970d67..db0b9de6f 100644 --- a/admin_manual/index.rst +++ b/admin_manual/index.rst @@ -94,6 +94,7 @@ contains the following topics: * :doc:`configuration/user_auth_ftp_smb_imap` * :doc:`configuration/user_auth_ldap` * :doc:`configuration/user_configuration` +* :doc:`configuration/user_provisioning_api` * :doc:`configuration/reset_admin_password` Maintenance