Nextcloud Ruby API

Fork info

Forked from https://github.com/Dwimcore/nextcloud

Added full file commenting and tagging support. For the latter, used the preliminary implementation as a guide from https://github.com/rahul100885/nextcloud

Added content_type param to Api#requset method, so that it can be used directly for APIs that require e.g. JSON request body.

Purpose

Wrapper gem for Ruby used for communicating with Nextcloud OCS and WebDAV API endpoints.

This gem provides features for User provisioning, Group and App management, control of Shares and Federated Cloud Shares, WebDAV functions for File / Folder creation, removal and other operations.

Installation

Add this line to your application's Gemfile:

gem "nextcloud"

And then execute:

$ bundle

Or install it yourself as:

$ gem install nextcloud

Usage

Initialize with endpoint bundles

To initialize an OCS client you can look at following example

ocs = Nextcloud.ocs(
  url: "https://cloud.yourdomain.com",
  username: "your_username",
  password: "your_password"
)

An URL has to be a base of your Nextcloud instance. For API requests, it will be parsed to https://cloud.yourdomain.com/ocs/v2.php/cloud/ or similar.

Once ocs is available you can use following methods to initiate specific classes:

ocs.user, ocs.app, ocs.group, ocs.file_sharing

If you intent to work with WebDAV api you can initialize a client with webdav:

webdav = Nextcloud.webdav(
  url: "https://cloud.yourdomain.com",
  username: "your_username",
  password: "your_password"
)

You can also initialize and work with both APIs (useful if credentials are same):

nextcloud = Nextcloud.new(
  url: "https://cloud.yourdomain.com",
  username: "your_username",
  password: "your_password"
)

ocs = nextcloud.ocs
webdav = nextcloud.webdav

Initialize specific APIs

Previously described method is recommended, however you can initialize in a different manner.

Initialize OCS Users API:

user = Nextcloud::Ocs::User.new(url: "…", username: "…", password: "…")

Initialize OCS Groups API:

group = Nextcloud::Ocs::Group.new(url: "…", username: "…", password: "…")

Initialize OCS Apps API:

app = Nextcloud::Ocs::App.new(url: "…", username: "…", password: "…")

Initialize OCS File Sharing API:

file_sharing = Nextcloud::Ocs::FileSharingApi.new(url: "…", username: "…", password: "…")

Initialize WebDAV Directory API:

directory = Nextcloud::Webdav::Directory.new(url: "…", username: "…", password: "…")

When initializing this way, to work with certain objects some circumstances might force you use set method. For example if you wish to list members of group admin, using first way you could simply write ocs.group('admin').members, in this case you will need to use group.set('admin').members. There is another way to set object of intereset by putting it into initialize arguments, like so Nextcloud::Ocs::Group.new({…credentials}, groupid="admin") it can be then reset with set. Corresponding parameter names for other classes are userid and appid.

OCS Api usage

These examples assume you have Nextcloud.ocs instance or relevant instance of Nextcloud::Ocs::{CLASS_NAME}.new stored in ocs variable.

User actions

Get list of users

users = ocs.user.all
# => [#<Nextcloud::Models::User:0x00000104d253c0 @id="your_user_1">, #<Nextcloud::Models::User:0x00000104d1f858 @id="your_user_2">]

last_user = user.last
=> #<Nextcloud::Models::User:0x000001042a2ba0 @id="your_user_2">

response_meta = users.meta
{"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}

Get a single user

user = ocs.user.find("your_user_1")
# => #<Nextcloud::Models::User:0x00000103964020 @enabled="true", @id="your_user_1", …, @meta={"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}>

Having user variable you have access to following attributes:

enabled
id
quota
email
displayname
phone
address
website
twitter
groups
language
meta

Again, here you can use user.meta to get service response status, code and message.

Create an user

meta = ocs.user.create("user3", "userPassword1!").meta
# => {"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}

Update an user

You can update an user attributes with key-value method.

Valid keys include:

quota
displayname
phone
address
website
twitter
password

meta = ocs.user.update("user3", "email", "new-address@some-domain.com").meta
# => {"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}

Disable user

meta = ocs.user.disable("user3").meta
# => {"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}

Enable user

meta = ocs.user.enable("user3").meta
# => {"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}

Delete user

meta = ocs.user.destroy("user3").meta
# => {"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}

Resend welcome email message

meta = ocs.user.resend_welcome("user3").meta
# => {"status"=>"ok", "statuscode"=>"200", "message"=>"OK"}