Redmine

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