3.2 REST API Group Service

As we transition to the new Hyland Community, some post links may be temporarily disrupted as we finalize redirects. We apologize for the inconvenience and are working to resolve this as quickly as possible. Details.

resplin

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

3.2
Design Document

Table of Contents

• 1 Group Service
  
  • 1.1 Data
    
    • 1.1.1 Group
  • 1.2 Resources
    
    • 1.2.1 Root Groups Collection
    • 1.2.2 Groups Collection
    • 1.2.3 Group
    • 1.2.4 Child Authorities
    • 1.2.5 Child Authority
    • 1.2.6 Parent Authorities
• 2 Modifications Required to Person Service
  
  • 2.1 Data
    
    • 2.1.1 Person

Group Service

Data

Note: All returned data will be contained in the standard JSON return structure:

{
   'data' : <resulting JSON data structure goes here>
}

Group

A group contains the following:

• shortName - The short name of the group.  This attribute is mandatory and is the unique identifier for the group.
  
• fullName - The full name of the group.  Calculated on the server from the short name.
  
• displayName - The groups display name.  read/write
  
• userCount - The number of users that are contained within the group.  read Only
  
• groupCount - The number of groups that are contained within the group. read Only
  
• isRootGroup - Indicates whether the group is a root group or not. read Only
  
• authorityType - The authority type.  Always set to 'Group' for a group.  Mandatory.
  
• url - Url to the group resource.
  

For future enhancements (More thought required here)

• isAdminAuthority - Indicates whether this group has admin authority.
  
• isInternalAuthority - Indicates whether this group is for internal use only.
  

JSON example:

{
   'shortName' : 'myGroup',
   'fullName' : 'GROUP_myGroup',
   'displayName' : 'My Group',
   'userCount' : 2,
   'groupCount' : 3,
   'isRootGroup' : true,
   'authorityType' : 'Group',
   'url' : '/api/groups/myGroup'   
}

Resources

Root Groups Collection

The resource to represent the collection all root groups.

Methods:

List all the root groups:

GET /api/rootgroups
   ?includeInternal={includeInternal?}
   

Create a root group(s):

POST /api/rootgroups
   => Groups[]
   

Groups Collection

Resource to represent the collection of all groups.

Methods:
Search groups by short name.

If a shortNameFilter value is provided only groups that contain the string in their short names will be returned.

Mrogers 11:05, 30 March 2009 (BST) should we allow regex here?

 
GET /api/groups
   ?shortNameFilter={shortNameFilter?}&includeInternal={includeInternal?}   
   

Group

Resource to represent a group.

Methods:

Get the details of a group:

GET /api/groups/{shortName}
   

Update the details of a group:

• displayName can be changed.
  

PUT /api/groups/{shortName}
   => Group
   

Delete a group and all it's dependants:

DELETE /api/groups/{shortName}

Child Authorities

Resource to represent the child users/groups of a group.

Methods:

Get a list of the child authorities of a group.  This contains both people and groups.  The authority type parameter can be used to only return authorities of the given type.

GET /api/groups/{shortName}/children
   ?authorityType={authorityType?}
   

Adds group(s) and user(s) as children of a group.  If the provided group does not exist it is created.

POST /api/groups/{shortName}/children
   => (Group|Person)[]

Child Authority

Resource to represent a child user/group of a group.

Methods:

Removes a person or group from a group.  The id is either the a user id or a group short name.

DELETE /api/groups/{shortName}/children/{id}

Parent Authorities

Resource to represent the parent groups of this group.

Methods:

Get a list of the parent groups of this parent.

GET /api/groups/{shortName}/parents?level='ALL'
   

Modifications Required to Person Service

Data

Person

Add the following values to the Person data:

• authorityType - Indicates the authority type.  Always set to 'User' for a person. Mandatory.
  
• isAdminAuthority - Indicates whether this user has admin authority.
  
• isInternalAuthority - Indicates whether this user is for internal use only.