CalGroups Web Services (API) Integration Guide
Table of Contents
1. Web Services Account
Contact calnet-admin@berkeley.edu to request a web services account.
2. General Information
- Server Domain Names:
- Test: https://group-test.berkeley.edu
- Production: https://calgroups.berkeley.edu
- URI Structure:
/grouper/servicesRest/json/v2_2_100/(groups|stems)/(group|stem name) - Headers:
Content-Type: text/x-json - Authentication: Basic HTTP Authentication. Ensure the API account has admin access to your groups/folders by adding it to the folder's admin group.
- Official Documentation: Grouper Web Services Reference
3. Membership Methods
Add Member (Single UID)
PUT https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup/members/212375
Reference: Add Member Sample
Add Group as a Member (Using UUID)
PUT https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup/members/c466a9d915044c72a67e8999f2d3ce4b
Add Multiple Members
Use person UID or group UUID as subjectId. Replace membership by setting replaceAllExisting to T.
URN: PUT https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup/members
Body:
{
"WsRestAddMemberRequest":{
"replaceAllExisting":"F",
"subjectLookups":[
{"subjectId":"212374"},
{"subjectId":"c466a9d915044c72a67e8999f2d3ce4b"},
{"subjectId":"212375"}
]
}
}
Body:
{
"WsRestAddMemberRequest":{
"replaceAllExisting":"F",
"subjectLookups":[
{"subjectId":"212374"},
{"subjectId":"c466a9d915044c72a67e8999f2d3ce4b"},
{"subjectId":"212375"}
]
}
}
Delete Member
DELETE https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup/members/1234
Get Members (List all members of a group)
GET https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup/members
Get Groups (List all groups for a specific UID)
GET https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/subjects/1234/groups
Has Member (Verify if UID is in group)
GET https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup/members/1234
4. Group and Stem Management
Group Save (Create Group)
POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup?wsLiteObjectType=WsRestGroupSaveLiteRequest&groupName=edu:berkeley:app:someapp:testgroup
Group Delete
DELETE https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups/edu:berkeley:app:someapp:testgroup
Stem Save (Create Folder)
POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/stems/edu:berkeley:app:someapp:teststem?wsLiteObjectType=WsRestStemSaveLiteRequest&stemName=edu:berkeley:app:someapp:teststem
Find Groups
Find all groups under a specified stem:
POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/groups?wsLiteObjectType=WsRestFindGroupsLiteRequest&queryFilterType=FIND_BY_STEM_NAME&stemName=edu:berkeley:app:someapp
Create a Composite Group
Body Snippet:
"wsGroup":{
"description":"my composite group description",
"detail":{
"compositeType":"intersection",
"hasComposite":"T",
"leftGroup":{"name":"edu:berkeley:official:employees:all-emp"},
"rightGroup":{"name":"edu:berkeley:app:someapp:my-adhoc-group"}
},
"name":"edu:berkeley:app:someapp:my-composite-group"
}
"wsGroup":{
"description":"my composite group description",
"detail":{
"compositeType":"intersection",
"hasComposite":"T",
"leftGroup":{"name":"edu:berkeley:official:employees:all-emp"},
"rightGroup":{"name":"edu:berkeley:app:someapp:my-adhoc-group"}
},
"name":"edu:berkeley:app:someapp:my-composite-group"
}
5. Provisioning Attributes
Use these methods to add or remove sync attributes for Google (bConnected), LDAP, or AD. The values for valueSystem are: bConnected, LDAPBerkeleyIMO, or AD.
Add Provisioning Attributes
URN: POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/attributeAssignments
Body Example (Sync to Google):
{ "WsRestAssignAttributesBatchRequest": {
"wsAssignAttributeBatchEntries": [
{ "wsOwnerGroupLookup": { "groupName": "edu:berkeley:org:testorg:testgroupname" },
"attributeAssignType": "group",
"attributeAssignOperation": "add_attr",
"wsAttributeDefNameLookup": { "name": "etc:provisioning:provisioningMarker" }
}
]
}}
Body Example (Sync to Google):
{ "WsRestAssignAttributesBatchRequest": {
"wsAssignAttributeBatchEntries": [
{ "wsOwnerGroupLookup": { "groupName": "edu:berkeley:org:testorg:testgroupname" },
"attributeAssignType": "group",
"attributeAssignOperation": "add_attr",
"wsAttributeDefNameLookup": { "name": "etc:provisioning:provisioningMarker" }
}
]
}}
Remove Provisioning Attributes
POST https://calgroups.berkeley.edu/grouper/servicesRest/json/v2_2_100/attributeAssignments
Body: { "WsRestAssignAttributesLiteRequest":{ "attributeAssignOperation":"remove_attr", ... }}
Body: { "WsRestAssignAttributesLiteRequest":{ "attributeAssignOperation":"remove_attr", ... }}
6. Support
Request access to a folder space using the CalGroups Service Request form.
If you have questions about CalGroups or the API, contact: calnet-admin@berkeley.edu.