Project

General

Profile

Rest Memberships » History » Revision 3

Revision 2 (Jean-Philippe Lang, 2012-02-06 11:46) → Revision 3/8 (Jean-Philippe Lang, 2012-02-06 12:05)

h1. Project Memberships 

 {{>toc}} 

 h2. /projects/:project_id/memberships.:format 

 h3. GET 

 Returns a paginated list of the project memberships. @:project_id@ can be either the project numerical id or the project identifier. 

 +Examples+: 

 <pre> 
 GET /projects/1/memberships.xml 
 GET /projects/redmine/memberships.xml 
 </pre> 

 +Response+: 

 <pre> 
 <?xml version="1.0" encoding="UTF-8"?> 
 <memberships type="array" limit="25" offset="0" total_count="2"> 
   <membership> 
     <id>1</id> 
     <project name="Redmine" id="1"/> 
     <user name="David Robert" id="17"/> 
     <roles type="array"> 
       <role name="Manager" id="1"/> 
     </roles> 
   </membership> 
   <membership> 
     <id>3</id> 
     <project name="Redmine" id="1"/> 
     <group name="Contributors" id="24"/> 
     <roles type="array"> 
       <role name="Contributor" id="3"/> 
     </roles> 
   </membership> 
   <membership> 
     <id>4</id> 
     <project name="Redmine" id="1"/> 
     <user name="John Smith" id="27"/> 
     <roles type="array"> 
       <role name="Developer" id="2" /> 
       <role name="Contributor" id="3" inherited="true" /> 
     </roles> 
   </membership> 
 </memberships> 
 </pre> 

 Notes: 
 * The membership owner can be either a user or a group (Groups management is not yet part of the API) 
 * In the above example, the @inherited="true"@ attribute on the last role means that this role was inherited from a group (eg. Jonh Smith belongs to the Contributors group and this group was added as a project member). John Smith's membership can not be deleted without deleting the group membership first. 
 * The memberships of a given user can be retrieved from the [[Rest_Users|Users API]]. 

 h3. POST 

 Adds a project member. 

 +Parameters+: 

 * @membership@ (required): a hash of the membership attributes, including: 

   * @user_id@ (required): the numerical id of the user 
   * @role_ids@ (required): an array of roles numerical ids 

 +Example+: 

 <pre> 
 POST /projects/redmine/memberships.xml 

 <membership> 
   <user_id>27</user_id> 
   <role_ids type="array"> 
     <role_id>2</role_id> 
   </role_ids> 
 </membership> 
 </pre> 

 +Response+: 

   * @201 Created@: membership was created 
   * @422 Unprocessable Entity@: membership was not created due to validation failures (response body contains the error messages) 

 h2. /memberships/:id.:format 

 h3. GET 

 Returns the membership of given @:id@. 

 +Examples+: 

 <pre> 
 GET /memberships/1.xml 
 </pre> 

 +Response+: 

 <pre> 
 <?xml version="1.0" encoding="UTF-8"?> 
 <membership> 
   <id>1</id> 
   <project name="Redmine" id="1"/> 
   <user name="David Robert" id="17"/> 
   <roles type="array"> 
     <role name="Developer" id="2"/> 
     <role name="Manager" id="1"/> 
   </roles> 
 </membership> 
 </pre> 

 h3. PUT 

 Updates the membership of given :id. Only the roles can be updated, the project and the user of a membership are read-only. 

 +Parameters+: 

 * @membership@ (required): a hash of the membership attributes, including: 

   * @role_ids@ (required): an array of roles numerical ids 

 +Example+: 

 <pre> 
 PUT /memberships/2.xml 

 <membership> 
   <role_ids type="array"> 
     <role_id>3</role_id> 
     <role_id>4</role_id> 
   </role_ids> 
 </membership> 
 </pre> 

 +Response+: 

   * @200 OK@: membership was updated 
   * @422 Unprocessable Entity@: membership was not updated due to validation failures (response body contains the error messages) 

 h3. DELETE 

 Deletes a memberships. 

 Memberships inherited from a group membership can not be deleted. You must delete the group membership. 

 +Parameters+: 

 _none_ 

 +Example+: 

 <pre> 
 DELETE /memberships/2.xml 
 </pre> 

 +Response+: 

   * @200 OK@: membership was deleted 
   * @422 Unprocessable Entity@: membership was not deleted