Project

General

Profile

Rest Memberships » History » Version 4

Jean-Philippe Lang, 2012-02-06 12:06
typo in example

1 1 Jean-Philippe Lang
h1. Project Memberships
2
3
{{>toc}}
4
5
h2. /projects/:project_id/memberships.:format
6
7
h3. GET
8
9
Returns a paginated list of the project memberships. @:project_id@ can be either the project numerical id or the project identifier.
10
11
+Examples+:
12
13
<pre>
14
GET /projects/1/memberships.xml
15
GET /projects/redmine/memberships.xml
16
</pre>
17
18
+Response+:
19
20
<pre>
21
<?xml version="1.0" encoding="UTF-8"?>
22 4 Jean-Philippe Lang
<memberships type="array" limit="25" offset="0" total_count="3">
23 1 Jean-Philippe Lang
  <membership>
24
    <id>1</id>
25
    <project name="Redmine" id="1"/>
26
    <user name="David Robert" id="17"/>
27
    <roles type="array">
28
      <role name="Manager" id="1"/>
29
    </roles>
30
  </membership>
31
  <membership>
32
    <id>3</id>
33
    <project name="Redmine" id="1"/>
34
    <group name="Contributors" id="24"/>
35
    <roles type="array">
36
      <role name="Contributor" id="3"/>
37
    </roles>
38
  </membership>
39
  <membership>
40
    <id>4</id>
41
    <project name="Redmine" id="1"/>
42
    <user name="John Smith" id="27"/>
43
    <roles type="array">
44
      <role name="Developer" id="2" />
45
      <role name="Contributor" id="3" inherited="true" />
46
    </roles>
47
  </membership>
48
</memberships>
49
</pre>
50
51 3 Jean-Philippe Lang
Notes:
52
* The membership owner can be either a user or a group (Groups management is not yet part of the API)
53
* 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.
54
* The memberships of a given user can be retrieved from the [[Rest_Users|Users API]].
55 1 Jean-Philippe Lang
56
h3. POST
57
58
Adds a project member.
59
60
+Parameters+:
61
62
* @membership@ (required): a hash of the membership attributes, including:
63
64
  * @user_id@ (required): the numerical id of the user
65
  * @role_ids@ (required): an array of roles numerical ids
66
67 2 Jean-Philippe Lang
+Example+:
68
69
<pre>
70
POST /projects/redmine/memberships.xml
71
72
<membership>
73
  <user_id>27</user_id>
74
  <role_ids type="array">
75
    <role_id>2</role_id>
76
  </role_ids>
77
</membership>
78
</pre>
79
80 1 Jean-Philippe Lang
+Response+:
81
82
  * @201 Created@: membership was created
83
  * @422 Unprocessable Entity@: membership was not created due to validation failures (response body contains the error messages)
84
85
h2. /memberships/:id.:format
86
87
h3. GET
88
89
Returns the membership of given @:id@.
90
91
+Examples+:
92
93
<pre>
94
GET /memberships/1.xml
95
</pre>
96
97
+Response+:
98
99
<pre>
100
<?xml version="1.0" encoding="UTF-8"?>
101
<membership>
102
  <id>1</id>
103
  <project name="Redmine" id="1"/>
104
  <user name="David Robert" id="17"/>
105
  <roles type="array">
106
    <role name="Developer" id="2"/>
107
    <role name="Manager" id="1"/>
108
  </roles>
109
</membership>
110
</pre>
111
112
h3. PUT
113
114
Updates the membership of given :id. Only the roles can be updated, the project and the user of a membership are read-only.
115
116
+Parameters+:
117
118
* @membership@ (required): a hash of the membership attributes, including:
119
120
  * @role_ids@ (required): an array of roles numerical ids
121
122 2 Jean-Philippe Lang
+Example+:
123
124
<pre>
125
PUT /memberships/2.xml
126
127
<membership>
128
  <role_ids type="array">
129
    <role_id>3</role_id>
130
    <role_id>4</role_id>
131
  </role_ids>
132
</membership>
133
</pre>
134
135 1 Jean-Philippe Lang
+Response+:
136
137
  * @200 OK@: membership was updated
138
  * @422 Unprocessable Entity@: membership was not updated due to validation failures (response body contains the error messages)
139
140
h3. DELETE
141
142
Deletes a memberships.
143
144
Memberships inherited from a group membership can not be deleted. You must delete the group membership.
145
146
+Parameters+:
147
148
_none_
149 2 Jean-Philippe Lang
150
+Example+:
151
152
<pre>
153
DELETE /memberships/2.xml
154
</pre>
155 1 Jean-Philippe Lang
156
+Response+:
157
158
  * @200 OK@: membership was deleted
159
  * @422 Unprocessable Entity@: membership was not deleted