Represents a user's membership in a location (site, group, etc.) in the system, works with the site/group entities and the user entities. In the documentation below, a membership ID is a string in the form USER_ID::LOCATION_REFERENCE (e.g., "aaronz::site:mySiteId").
HTTP response codes as returned by the system:
200 - OK (request is ok and content returned)
201 - CREATED (request created new content, URL and id of content in the header)
204 - NO CONTENT (request is ok but no content to return)
400 - ERROR (general error in the request, probably invalid parameters or data)
401 - UNAUTHORIZED (user authentication required for this request)
403 - FORBIDDEN (authorization required, insufficient privileges, user is already authenticated)
404 - NOT FOUND (resource not found, URL is invalid in some way, id or action are invalid)
405 - METHOD NOT ALLOWED (the method is not supported for this entity type)
406 - NOT ACCEPTABLE (the data format requested is unavailable for this entity type)
500 - INTERNAL SERVER ERROR (general server failure, probably a failure in the provider)
501 - NOT IMPLEMENTED (indicates that a prefix is invalid)
Sample Entity URLs (_id=':ID:') [may not be valid]:
Response Code Details: 200 plus data; 404 if not found, 406 if format unavailable
By default, retrieves a list of all site memberships for the current user. Optional query parameters: "includeSites=false" filters out site memberships; "includeGroups=true" retrieves group memberships; "_locationReference=LOCATION_REFERENCE" returns all memberships in the specified site or group; "user=USER_ID" (or "userId=USER_ID" or "_userReference=USER_REFERENCE") returns the given user's memberships; "includeMemberDetails=true" to return member full details of just the role of the user, cannot use this with includeGroups=true; "role=ROLE_STRING" (or "roleId=ROLE_STRING") restricts the list to the specified member role.
Response Code Details: 201 plus id (EntityId); 400 if inputs invalid
(POST) Add the membership specified by the ID. Alternatively, a POST to the simple "/membership" URL can specify "userId" and "locationReference" request parameters. In either case, optional request parameters are: "memberRole" string (default for joinable site memberships is the default joiner role); "active" Boolean value (default is true). Can do a batch add to the same location using the same role by specifying a "userIds" parameter (an array of user IDs).
Response Code Details: 200 plus data; 404 if not found, 406 if format unavailable
Response Code Details: 204; 400 if inputs invalid
(POST) Modify the membership specified by the ID. Alternatively, a POST to the "/membership" URL can specify "userId" and "locationReference" request parameters. In either case, optional request parameters are: "memberRole" string; "active" Boolean value. Can do a batch update to the same location using the same role and active setting by specifying a "userIds" parameter (an array of user IDs).
Response Code Details: 204; 404 if not found
(DELETE) Delete the membership specified by the ID. Multiple memberships can be deleted from the same location by specifying a "userIds" parameter (an array of user IDs).
Custom Actions
site :
* :
[/membership/site] (
html) (
xml) (
json) (
form)
The URL format is "/membership/site/:SITE_ID:".
(GET) will return all memberships in the specified site.
(POST) will add one or more site memberships via an array of "userSearchValues" request parameters (each of which is a user ID, user EID, or email address), along with a "memberRole" string (default for joinable site memberships is the default joiner role) and "active" Boolean value (default is true). Response headers may include "x-warning-not-found" (for a list of invalid userSearchValues) and "x-warning-already-members" (for a list of userSearchValues which were already site members).
unjoin :
new (POST) :
[/membership/unjoin]
Allows a user without permissions in a site to unjoin from it, works with the current user only: /membership/unjoin/site/siteId
sitebyjson :
new (POST) :
[/membership/sitebyjson]
The URL format is "/membership/sitebyjson/:SITE_ID:".
(POST) will add one or more site memberships via an chunk of JSON supplied in the 'json' request parameter.
The JSON needs to be formatted like this:
[ {"id": "user1", "role": "access"}, {"id": "user2","role": "maintain"} ]
Three response headers will be set:
x-success-count, which contains the number of successful additions
x-warning-not-found, which contains a comma separated list of user ids which didn't exist
x-warning-already-members, which contains a comma separated list of user ids which were already in the site
join :
new (POST) :
[/membership/join]
Allows a user without permissions in a site to join it, works with the current user only: /membership/join/site/siteId
fastroles :
* :
[/membership/fastroles] (
html) (
xml) (
json) (
form)
Allows for retrieval of current role in site only quickly. Use the format "/membership/fastroles/:userId:" (or userEid) or current user if none specified. A shortcut for includeMemberDetail=false.
group :
* :
[/membership/group] (
html) (
xml) (
json) (
form)
The URL format is "/membership/group/:groupId:"
(GET) will return all memberships for a group.
(POST) will update user group membership. Mandatory POST Parameters: 'userIds' a comma separated list of users (eid or id). 'action' can have values: update, add or remove. If update, replace the current membership with the provided list. If add, add the list to the existing membership, if remove, remove the list from the existing membership.
Entity class : org.sakaiproject.entitybroker.providers.model.EntityMember
Type :: bean
|
Name |
Type |
Status |
| 1) | active | boolean | Read/Write |
| 2) | id | string | Read Only |
| 3) | lastLoginTime | java.util.Date | Read Only |
| 4) | locationReference | string | Read/Write * required |
| 5) | memberRole | string | Read/Write * required |
| 6) | provided | boolean | Read/Write |
| 7) | userDisplayId | string | Read Only |
| 8) | userDisplayName | string | Read Only |
| 9) | userEid | string | Read Only |
| 10) | userEmail | string | Read Only |
| 11) | userFirstName | string | Read Only |
| 12) | userId | string | Read/Write * required |
| 13) | userLastName | string | Read Only |
| 14) | userSortName | string | Read Only |
Data and Request Handling
Output formats : html, xml, json, form
Input formats : html, xml, json
No Access Provider registered for request processing
Capabilities
| Name | Type | Description |
|---|
| 1 | CoreEntityProvider | org.sakaiproject.entitybroker.entityprovider.CoreEntityProvider | |
| 2 | EntityProvider | org.sakaiproject.entitybroker.entityprovider.EntityProvider | |
| 3 | ActionsExecutable | org.sakaiproject.entitybroker.entityprovider.capabilities.ActionsExecutable | |
| 4 | CRUDable | org.sakaiproject.entitybroker.entityprovider.capabilities.CRUDable | |
| 5 | CollectionResolvable | org.sakaiproject.entitybroker.entityprovider.capabilities.CollectionResolvable | |
| 6 | Createable | org.sakaiproject.entitybroker.entityprovider.capabilities.Createable | |
| 7 | Deleteable | org.sakaiproject.entitybroker.entityprovider.capabilities.Deleteable | |
| 8 | Describeable | org.sakaiproject.entitybroker.entityprovider.capabilities.Describeable | |
| 9 | Inputable | org.sakaiproject.entitybroker.entityprovider.capabilities.Inputable | |
| 10 | Outputable | org.sakaiproject.entitybroker.entityprovider.capabilities.Outputable | |
| 11 | RESTful | org.sakaiproject.entitybroker.entityprovider.capabilities.RESTful | |
| 12 | Redirectable | org.sakaiproject.entitybroker.entityprovider.capabilities.Redirectable | |
| 13 | Resolvable | org.sakaiproject.entitybroker.entityprovider.capabilities.Resolvable | |
| 14 | Sampleable | org.sakaiproject.entitybroker.entityprovider.capabilities.Sampleable | |
| 15 | Saveable | org.sakaiproject.entitybroker.entityprovider.capabilities.Saveable | |
| 16 | Updateable | org.sakaiproject.entitybroker.entityprovider.capabilities.Updateable | |
REST:: 1.0.1 SVN: $Revision$ : $Date$