Scyld Cloud Controller Documentation

Group API

The Group API presents an interface for creating, modifying, and deleting system groups. These are real UNIX system groups, and are useful for collaborating on projects by organizing multiple users into one or more groups, then using standard Linux group permissions to control access to files/folders.

The Group API can be used to create/modify/delete secondary groups. A user’s primary group cannot be changed.

Group Object

A Group object has the following properties:

  • group-id – string. A UUID uniquely identifying this Group object.
  • cloudauth-id – string. A UUID identifying the Scyld Cloud Auth user ID associated with this group.
  • group-name – string. The UNIX group name associated with this group.
  • group-members – list. A list of UNIX system user names in the group.

All fields are required.

API Methods

/group

The /group URI accepts HTTP GET and HTTP POST

GET

An HTTP GET on /group will return a list of Group objects that the requester has permission to see.

A requester with the superuser role in Scyld Cloud Auth would see all Group objects in the system. A requester with no special permissions or managed users will see only Groups owned by themselves. A requester with managed users will see their own Groups, plus the Groups belonging to their managed users.

The following querystring parameters can be specified to further limit the results:

  • group-name – Search for accessible Groups that have a matching group-name property (i.e. “dept1”).
  • cloudauth-id – Search for accessible Groups that are owned by the given cloudauth-id.

group-name and cloudauth-id parameters may not be used at the same time.

Group Response Schema

The response from the GET /group call is governed by the following JSON-Schema:





Examples


Get a list of groups you have access to:






POST


An HTTP POST on /group will create a new Group.


When creating a new Group, one must provide the UNIX group-name that the group
will have.  You may optionally specify a list of UNIX user-names to add to the
group immediately.  These must be users that you own or manage, or else you will
receive an error.


Group POST Schema


The data format for POST /group is governed by the following JSON-Schema:





Examples


Create a new group, initially with no members:






/group/<id>


The /group/<id> URI accepts HTTP GET, HTTP PUT, and HTTP DELETE.


The <id> field is the UUID that identifies a specific Group object.


GET


An HTTP Get on /group/<id> will return data in the exact same format as /group
(see Group Response Schema), but will contain at most one item – the
Group object referenced by UUID.



PUT


An HTTP PUT on /group/<id> will attempt to modify the properties of the Group object.


There is only one property of the Group object that can be modified:


    

  • group-members – The UNIX system-names that are members of this Group object.
    • 



There are three “actions” that can be taken when modifying a user
property:


    

  • add – This will add the given items to the property, leaving the existing ones intact.
    • 

  • delete – This will delete the given items from the property.
    • 

  • replace – This will delete all existing items from the property, and replace them with the given items.
    • 




Group PUT Schema


The data format for PUT /group/<id> is governed by the following JSON-Schema:





DELETE


An HTTP DELETE on an existing Group object will delete that group from the
system, removing all members and the definition itself.



          
 
 
 

          

          

          
          
Scyld Cloud Controller

          

          
          
SCM API Documentation