membership (xml)

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").
RESTful URLs: http://microformats.org/wiki/rest/urls
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]:

Entity Collection URL: GET /membership (html) (xml) (json) (form)
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.
Create Entity URL: POST /membership (form)
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).
Show Entity URL: GET /membership/:ID: (html) (xml) (json) (form)
Response Code Details: 200 plus data; 404 if not found, 406 if format unavailable
Update Entity URL: PUT /membership/:ID: (form)
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).
Delete Entity URL: DELETE /membership/:ID: (form)
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) activebooleanRead/Write
2) idstringRead Only
3) lastLoginTimejava.util.DateRead Only
4) locationReferencestringRead/Write * required
5) memberRolestringRead/Write * required
6) providedbooleanRead/Write
7) userDisplayIdstringRead Only
8) userDisplayNamestringRead Only
9) userEidstringRead Only
10) userEmailstringRead Only
11) userIdstringRead/Write * required
12) userSortNamestringRead Only

Data and Request Handling

Output formats : html, xml, json, form
Input formats : html, xml, json
No Access Provider registered for request processing

Capabilities

NameTypeDescription
1CoreEntityProviderorg.sakaiproject.entitybroker.entityprovider.CoreEntityProvider
2EntityProviderorg.sakaiproject.entitybroker.entityprovider.EntityProvider
3ActionsExecutableorg.sakaiproject.entitybroker.entityprovider.capabilities.ActionsExecutable
4CRUDableorg.sakaiproject.entitybroker.entityprovider.capabilities.CRUDable
5CollectionResolvableorg.sakaiproject.entitybroker.entityprovider.capabilities.CollectionResolvable
6Createableorg.sakaiproject.entitybroker.entityprovider.capabilities.Createable
7Deleteableorg.sakaiproject.entitybroker.entityprovider.capabilities.Deleteable
8Describeableorg.sakaiproject.entitybroker.entityprovider.capabilities.Describeable
9Inputableorg.sakaiproject.entitybroker.entityprovider.capabilities.Inputable
10Outputableorg.sakaiproject.entitybroker.entityprovider.capabilities.Outputable
11RESTfulorg.sakaiproject.entitybroker.entityprovider.capabilities.RESTful
12Redirectableorg.sakaiproject.entitybroker.entityprovider.capabilities.Redirectable
13Resolvableorg.sakaiproject.entitybroker.entityprovider.capabilities.Resolvable
14Sampleableorg.sakaiproject.entitybroker.entityprovider.capabilities.Sampleable
15Saveableorg.sakaiproject.entitybroker.entityprovider.capabilities.Saveable
16Updateableorg.sakaiproject.entitybroker.entityprovider.capabilities.Updateable

REST:: 1.0.1 SVN: $Revision$ : $Date$