Rest Memberships » History » Revision 5
Revision 4 (Jean-Philippe Lang, 2012-02-06 12:06) → Revision 5/8 (Jean-Philippe Lang, 2012-06-03 15:17)
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="3">
<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 ([[Rest_Groups|Groups API]] (Groups management is added in Redmine 2.1) 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