Javascript API v1

Calling the API

in the PHP of your app, you will need to load the Circles.js:

<?php
script('circles', 'circles.v1.circles');
script('circles', 'circles.v1.members');
script('circles', 'circles.v1.links');
script('circles', 'circles.v1');
?>

Then from your Javascript:

var api = OCA.Circles.api;

---

Using the API to manage Circles

api.createCircle(type, name, callback);

Create a new circle and make the current user its owner.
You must specify type and name. type is one of this value:

CIRCLES_PERSONAL is 1 or 'personal';
CIRCLES_HIDDEN is 2 or 'hidden';
CIRCLES_PRIVATE is 4 or 'private';
CIRCLES_PUBLIC is 8 or 'public'; 

api.joinCircle(circleId, callback);

This function will make the current user joining a circle identified by its Id. If the type

api.leaveCircle(circleId, callback);

This function will make the current user leaving the circle identified by its Id. Will fail if user is the owner of the circle.

api.listCircles(type, name, level, callback);

This function list all circles fitting a search regarding its name and the level and the rights from the current user. In case of Hidden circle, name needs to be complete so the circle is included in the list (or if the current user is the owner)

example: api.listCircles('all', '', 8, callback); will returns all circles when the current user is at least an Admin.

api.detailsCircle(circleId, callback);

Returns details on the circle. If the current user is a member, the members list will be return as well.

api.destroyCircle(circleId, callback);

This function will destroy the circle if the current user is the Owner.

---

Using the API to manage Members

api.addMember(circleId, userId, callback);

This function will add a user as member of the circle. Current user need at least to be Moderator.

api.removeMember(circleId, userId, callback);

This function will remove a member from the circle. Current user needs to be at least Moderator and have a higher level that the targeted member.

api.levelMember(circleId, userId, level, callback);

Edit the level of a member of the circle. The current level of the target needs to be lower than the user that initiate the process (ie. the current user). The new level of the target cannot be the same than the current level of the user that initiate the process (ie. the current user).

---

Using the API to manage Shares

api.shareToCircle(circleId, source, type, item, callback);

This function will share an item (array) to the circle identified by its Id.
Source is the app that is sharing the item and type can be used by the app to identified the payload.

---

Using the API to manage Links

api.linkCircle(circleId, remote, callback);

Initiate a link procedure. Current user must be at least Admin of the circle.
circleId is the local circle and remote is the target for the link.
Remote format is: <circle_name>@<remote_host> when remote_host must be a valid HTTPS address.