# this defines the entity description for membership
membership = 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").
membership.view.new = (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).
membership.view.delete = (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).
membership.view.edit = (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).
membership.view.list = 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.
membership.action.site = The URL format is "/membership/site/:SITE_ID:". <br/> \
(GET) will return all memberships in the specified site. <br/> \
(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).
membership.action.sitebyjson = The URL format is "/membership/sitebyjson/:SITE_ID:". <br/> \
(POST) will add one or more site memberships via an chunk of JSON supplied in the 'json' request parameter.<br/> \
<br/>\
The JSON needs to be formatted like this: <br/> \
<br/>\
[ {"id": "user1", "role": "access"}, {"id": "user2\","role": "maintain"} ]<br/> \
<br/>\
Three response headers will be set:<br/> \
<br/>\
<b>x-success-count</b>, which contains the number of successful additions<br/> \
<b>x-warning-not-found</b>, which contains a comma separated list of user ids which didn't exist<br/>  \
<b>x-warning-already-members</b>, which contains a comma separated list of user ids which were already in the site
membership.action.group = The URL format is "/membership/group/:groupId:" <br/> \
(GET) will return all memberships for a group. <br/> \
(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. 
membership.action.join = Allows a user without permissions in a site to join it, works with the current user only: /membership/join/site/siteId
membership.action.unjoin = Allows a user without permissions in a site to unjoin from it, works with the current user only: /membership/unjoin/site/siteId
membership.action.fastroles = 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.
