blob: 52c505a572e08cdffcfe8743d933da8f4a9eac82 [file] [log] [blame]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001= Gerrit Code Review - /groups/ REST API
Edwin Kempind0a63922013-01-23 16:32:59 +01002
3This page describes the group related REST endpoints.
4Please also take note of the general information on the
5link:rest-api.html[REST API].
6
Edwin Kempin578fff72013-02-11 08:08:27 +01007[[group-endpoints]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08008== Group Endpoints
Edwin Kempind0a63922013-01-23 16:32:59 +01009
Edwin Kempin76202742013-02-15 13:51:50 +010010[[list-groups]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080011=== List Groups
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -080012--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +010013'GET /groups/'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -080014--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +010015
Edwin Kempind0a63922013-01-23 16:32:59 +010016Lists the groups accessible by the caller. This is the same as
17using the link:cmd-ls-groups.html[ls-groups] command over SSH,
18and accepts the same options as query parameters.
19
Edwin Kempin987d5432013-02-04 10:20:44 +010020As result a map is returned that maps the group names to
21link:#group-info[GroupInfo] entries. The entries in the map are sorted
22by group name.
23
Edwin Kempin37440832013-02-06 11:36:00 +010024.Request
Edwin Kempind0a63922013-01-23 16:32:59 +010025----
26 GET /groups/ HTTP/1.0
Edwin Kempin37440832013-02-06 11:36:00 +010027----
Edwin Kempind0a63922013-01-23 16:32:59 +010028
Edwin Kempin37440832013-02-06 11:36:00 +010029.Response
30----
Edwin Kempind0a63922013-01-23 16:32:59 +010031 HTTP/1.1 200 OK
32 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +090033 Content-Type: application/json; charset=UTF-8
Edwin Kempind0a63922013-01-23 16:32:59 +010034
35 )]}'
36 {
37 "Administrators": {
Edwin Kempind0a63922013-01-23 16:32:59 +010038 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
Edwin Kempine05c9642013-02-11 09:36:21 +010039 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
40 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +010041 },
Edwin Kempind0a63922013-01-23 16:32:59 +010042 "description": "Gerrit Site Administrators",
43 "group_id": 1,
Edwin Kempinc6993fb2013-02-11 12:39:13 +010044 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +020045 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
46 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempind0a63922013-01-23 16:32:59 +010047 },
48 "Anonymous Users": {
Edwin Kempind0a63922013-01-23 16:32:59 +010049 "id": "global%3AAnonymous-Users",
Edwin Kempine05c9642013-02-11 09:36:21 +010050 "url": "#/admin/groups/uuid-global%3AAnonymous-Users",
51 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +010052 },
Edwin Kempind0a63922013-01-23 16:32:59 +010053 "description": "Any user, signed-in or not",
54 "group_id": 2,
Edwin Kempinc6993fb2013-02-11 12:39:13 +010055 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +020056 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
57 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempind0a63922013-01-23 16:32:59 +010058 },
59 "MyProject_Committers": {
Edwin Kempind0a63922013-01-23 16:32:59 +010060 "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
Edwin Kempine05c9642013-02-11 09:36:21 +010061 "url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
62 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +010063 "visible_to_all": true,
64 },
Edwin Kempind0a63922013-01-23 16:32:59 +010065 "group_id": 6,
Edwin Kempinc6993fb2013-02-11 12:39:13 +010066 "owner": "MyProject_Committers",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +020067 "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
68 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempind0a63922013-01-23 16:32:59 +010069 },
Patrick Hiesele587c402020-08-07 16:11:29 +020070 "Service Users": {
Edwin Kempind0a63922013-01-23 16:32:59 +010071 "id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
Edwin Kempine05c9642013-02-11 09:36:21 +010072 "url": "#/admin/groups/uuid-5057f3cbd3519d6ab69364429a89ffdffba50f73",
73 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +010074 },
Patrick Hiesele587c402020-08-07 16:11:29 +020075 "description": "Service accounts that interact with Gerrit",
Edwin Kempind0a63922013-01-23 16:32:59 +010076 "group_id": 4,
Edwin Kempinc6993fb2013-02-11 12:39:13 +010077 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +020078 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
79 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempind0a63922013-01-23 16:32:59 +010080 },
81 "Project Owners": {
Edwin Kempind0a63922013-01-23 16:32:59 +010082 "id": "global%3AProject-Owners",
Edwin Kempine05c9642013-02-11 09:36:21 +010083 "url": "#/admin/groups/uuid-global%3AProject-Owners",
84 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +010085 },
Edwin Kempind0a63922013-01-23 16:32:59 +010086 "description": "Any owner of the project",
87 "group_id": 5,
Edwin Kempinc6993fb2013-02-11 12:39:13 +010088 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +020089 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
90 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempind0a63922013-01-23 16:32:59 +010091 },
92 "Registered Users": {
Edwin Kempind0a63922013-01-23 16:32:59 +010093 "id": "global%3ARegistered-Users",
Edwin Kempine05c9642013-02-11 09:36:21 +010094 "url": "#/admin/groups/uuid-global%3ARegistered-Users",
95 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +010096 },
Edwin Kempind0a63922013-01-23 16:32:59 +010097 "description": "Any signed-in user",
98 "group_id": 3,
Edwin Kempinc6993fb2013-02-11 12:39:13 +010099 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200100 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
101 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempind0a63922013-01-23 16:32:59 +0100102 }
103 }
104----
105
Edwin Kempina64c4b92013-01-23 11:30:40 +0100106.Get all groups
107****
108get::/groups/
109****
110
Edwin Kempinabaab5462013-02-11 15:30:19 +0100111[[group-options]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800112==== Group Options
Edwin Kempinabaab5462013-02-11 15:30:19 +0100113Additional fields can be obtained by adding `o` parameters, each option
114requires more lookups and slows down the query response time to the
115client so they are generally disabled by default. Optional fields are:
116
117[[includes]]
118--
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +0200119* `INCLUDES`: include list of direct subgroups.
Edwin Kempinabaab5462013-02-11 15:30:19 +0100120--
121
122[[members]]
123--
124* `MEMBERS`: include list of direct group members.
125--
126
David Pursehouse0442e5972017-09-22 20:44:29 +0900127==== Find groups that are owned by another group
128
David Pursehouse19275192020-05-07 10:39:40 +0900129By setting `owned-by` and specifying the link:#group-id[\{group-id\}] of another
David Pursehouse0442e5972017-09-22 20:44:29 +0900130group, it is possible to find all the groups for which the owning group is the
131given group.
132
133.Request
134----
David Pursehouse19275192020-05-07 10:39:40 +0900135 GET /groups/?owned-by=7ca042f4d5847936fcb90ca91057673157fd06fc HTTP/1.0
David Pursehouse0442e5972017-09-22 20:44:29 +0900136----
137
138.Response
139----
140 HTTP/1.1 200 OK
141 Content-Disposition: attachment
142 Content-Type: application/json; charset=UTF-8
143
144 )]}'
145 {
146 "MyProject-Committers": {
147 "id": "9999c971bb4ab872aab759d8c49833ee6b9ff320",
148 "url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
149 "options": {
150 "visible_to_all": true
151 },
152 "description":"contains all committers for MyProject",
153 "group_id": 551,
154 "owner": "MyProject-Owners",
155 "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
156 "created_on": "2013-02-01 09:59:32.126000000"
157 }
158 }
159----
160
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800161==== Check if a group is owned by the calling user
Edwin Kempina3b4b632013-02-11 10:33:55 +0100162By setting the option `owned` and specifying a group to inspect with
Edwin Kempina757d712017-01-16 14:46:43 +0100163the option `group`/`g`, it is possible to find out if this group is
164owned by the calling user.
165
166[NOTE] Earlier the `group`/`g` option was named `query`/`q`. Using
167`query`/`q` still works, but this option is deprecated and may be
168removed in future. Hence all users should be adapted to use
169`group`/`g` instead.
Edwin Kempina3b4b632013-02-11 10:33:55 +0100170
171.Request
172----
173 GET /groups/?owned&q=MyProject-Committers HTTP/1.0
174----
175
176If the group is owned by the calling user, the returned map contains
177this group. If the calling user doesn't own this group an empty map is
178returned.
179
180.Response
181----
182 HTTP/1.1 200 OK
183 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900184 Content-Type: application/json; charset=UTF-8
Edwin Kempina3b4b632013-02-11 10:33:55 +0100185
186 )]}'
187 {
188 "MyProject-Committers": {
Edwin Kempina3b4b632013-02-11 10:33:55 +0100189 "id": "9999c971bb4ab872aab759d8c49833ee6b9ff320",
Edwin Kempina3b4b632013-02-11 10:33:55 +0100190 "url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
191 "options": {
Edwin Kempina3b4b632013-02-11 10:33:55 +0100192 "visible_to_all": true
193 },
194 "description":"contains all committers for MyProject",
195 "group_id": 551,
Edwin Kempinc6993fb2013-02-11 12:39:13 +0100196 "owner": "MyProject-Owners",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200197 "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
198 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempina3b4b632013-02-11 10:33:55 +0100199 }
200 }
201----
202
Anthony Chindc783292014-04-10 11:14:41 -0400203[[group-limit]]
204==== Group Limit
205The `/groups/` URL also accepts a limit integer in the `n` parameter.
206This limits the results to show `n` groups.
207
208Query the first 25 groups in group list.
209----
210 GET /groups/?n=25 HTTP/1.0
211----
212
213The `/groups/` URL also accepts a start integer in the `S` parameter.
214The results will skip `S` groups from group list.
215
216Query 25 groups starting from index 50.
217----
218 GET /groups/?n=25&S=50 HTTP/1.0
219----
220
Yuxuan 'fishy' Wang8c485252015-09-08 17:53:23 -0700221[[suggest-group]]
222==== Suggest Group
David Pursehouse9b9bdec2016-02-18 14:21:20 +0900223The `suggest` or `s` option indicates a user-entered string that
Yuxuan 'fishy' Wang8c485252015-09-08 17:53:23 -0700224should be auto-completed to group names.
225If this option is set and `n` is not set, then `n` defaults to 10.
226
David Pursehouse9b9bdec2016-02-18 14:21:20 +0900227When using this option, the `project` or `p` option can be used to
228name the current project, to allow context-dependent suggestions.
Yuxuan 'fishy' Wang8c485252015-09-08 17:53:23 -0700229
Edwin Kempina757d712017-01-16 14:46:43 +0100230Not compatible with `visible-to-all`, `owned`, `user`, `match`,
231`group`, or `S`.
Yuxuan 'fishy' Wang8c485252015-09-08 17:53:23 -0700232(Attempts to use one of those options combined with `suggest` will
233error out.)
234
235.Request
236----
237 GET /groups/?suggest=ad&p=All-Projects HTTP/1.0
238----
239
240.Response
241----
242 HTTP/1.1 200 OK
243 Content-Disposition: attachment
244 Content-Type: application/json; charset=UTF-8
245
246 )]}'
247 {
248 "Administrators": {
249 "url": "#/admin/groups/uuid-59b92f35489e62c80d1ab1bf0c2d17843038df8b",
250 "options": {},
251 "description": "Gerrit Site Administrators",
252 "group_id": 1,
253 "owner": "Administrators",
254 "owner_id": "59b92f35489e62c80d1ab1bf0c2d17843038df8b",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200255 "created_on": "2013-02-01 09:59:32.126000000",
Yuxuan 'fishy' Wang8c485252015-09-08 17:53:23 -0700256 "id": "59b92f35489e62c80d1ab1bf0c2d17843038df8b"
257 }
258 }
259----
260
David Pursehouse969e6742017-07-12 20:12:26 +0900261Regex(r)::
262Limit the results to those groups that match the specified regex.
263+
264Boundary matchers '^' and '$' are implicit. For example: the regex 'test.*' will
265match any groups that start with 'test' and regex '.*test' will match any
266group that end with 'test'.
267+
268The match is case sensitive.
269+
270List all groups that match regex `test.*group`:
271+
272.Request
273----
274 GET /groups/?r=test.*group HTTP/1.0
275----
276+
277.Response
278----
279 HTTP/1.1 200 OK
280 Content-Disposition: attachment
281 Content-Type: application/json; charset=UTF-8
282
283 )]}'
284 {
285 "test/some-group": {
286 "url": "#/admin/groups/uuid-59b92f35489e62c80d1ab1bf0c2d17843038df8b",
287 "options": {},
288 "description": "Gerrit Site Administrators",
289 "group_id": 1,
290 "owner": "Administrators",
291 "owner_id": "59b92f35489e62c80d1ab1bf0c2d17843038df8b",
292 "created_on": "2013-02-01 09:59:32.126000000",
293 "id": "59b92f35489e62c80d1ab1bf0c2d17843038df8b"
294 }
295 "test/some-other-group": {
296 "url": "#/admin/groups/uuid-99b92f35489e62c80d1ab1bf0c2d17843038df8b",
297 "options": {},
298 "description": "Gerrit Site Administrators",
299 "group_id": 1,
300 "owner": "Administrators",
301 "owner_id": "99b92f35489e62c80d1ab1bf0c2d17843038df8b",
302 "created_on": "2014-02-01 09:59:32.126000000",
303 "id": "99b92f35489e62c80d1ab1bf0c2d17843038df8b"
304 }
305 }
306
307----
308
Paladox none3cbb5302017-07-11 13:41:03 +0000309Substring(m)::
310Limit the results to those groups that match the specified substring.
311+
David Pursehouse3cd948d2017-07-13 09:52:03 +0900312The match is case insensitive.
313+
Paladox none3cbb5302017-07-11 13:41:03 +0000314List all groups that match substring `test/`:
315+
316.Request
317----
318 GET /groups/?m=test%2F HTTP/1.0
319----
320+
321.Response
322----
323 HTTP/1.1 200 OK
324 Content-Disposition: attachment
325 Content-Type: application/json; charset=UTF-8
326
327 )]}'
328 {
329 "test/test": {
330 "url": "#/admin/groups/uuid-786a95e85f9a2223a96545f10003f396aba871f2",
331 "options": {},
332 "group_id": 15,
333 "owner": "test/test",
334 "owner_id": "786a95e85f9a2223a96545f10003f396aba871f2",
335 "created_on": "2017-07-11 13:56:24.000000000",
336 "id": "786a95e85f9a2223a96545f10003f396aba871f2"
337 }
338 }
339----
340
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100341[[query-groups]]
342=== Query Groups
343--
David Pursehouseb9e70b32019-09-27 16:55:11 +0900344'GET /groups/?query=<query>'
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100345--
346
347Queries internal groups visible to the caller. The
348link:user-search-groups.html#_search_operators[query string] must be
David Pursehouseb9e70b32019-09-27 16:55:11 +0900349provided by the `query` parameter. The `start` and `limit` parameters
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100350can be used to skip/limit results.
351
352As result a list of link:#group-info[GroupInfo] entities is returned.
353
354.Request
355----
David Pursehouseb9e70b32019-09-27 16:55:11 +0900356 GET /groups/?query=inname:test HTTP/1.0
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100357----
358
359.Response
360----
361 HTTP/1.1 200 OK
362 Content-Disposition: attachment
363 Content-Type: application/json; charset=UTF-8
364
365 )]}'
366 [
367 {
Edwin Kempina45b0722017-01-03 16:15:01 +0100368 "url": "#/admin/groups/uuid-68236a40ca78de8be630312d8ba50250bc5638ae",
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100369 "options": {},
Edwin Kempina45b0722017-01-03 16:15:01 +0100370 "description": "Group for running tests on MyProject",
371 "group_id": 20,
372 "owner": "MyProject-Test-Group",
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100373 "owner_id": "59b92f35489e62c80d1ab1bf0c2d17843038df8b",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200374 "created_on": "2013-02-01 09:59:32.126000000",
Edwin Kempina45b0722017-01-03 16:15:01 +0100375 "id": "68236a40ca78de8be630312d8ba50250bc5638ae"
376 },
377 {
378 "url": "#/admin/groups/uuid-99a534526313324a2667025c3f4e089199b736aa",
379 "options": {},
380 "description": "Testers for ProjectX",
381 "group_id": 17,
382 "owner": "ProjectX-Testers",
383 "owner_id": "59b92f35489e62c80d1ab1bf0c2d17843038df8b",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200384 "created_on": "2013-02-01 09:59:32.126000000",
Edwin Kempina45b0722017-01-03 16:15:01 +0100385 "id": "99a534526313324a2667025c3f4e089199b736aa"
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100386 }
387 ]
388----
389
Edwin Kempinfadf3632017-01-03 15:16:17 +0100390If the number of groups matching the query exceeds either the internal
391limit or a supplied `limit` query parameter, the last group object has
392a `_more_groups: true` JSON field set.
393
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100394[[group-query-limit]]
395==== Group Limit
David Pursehouseb9e70b32019-09-27 16:55:11 +0900396The `/groups/?query=<query>` URL also accepts a limit integer in the
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100397`limit` parameter. This limits the results to `limit` groups.
398
399Query the first 25 groups in group list.
400----
David Pursehouseb9e70b32019-09-27 16:55:11 +0900401 GET /groups/?query=<query>&limit=25 HTTP/1.0
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100402----
403
404The `/groups/` URL also accepts a start integer in the `start`
405parameter. The results will skip `start` groups from group list.
406
407Query 25 groups starting from index 50.
408----
David Pursehouseb9e70b32019-09-27 16:55:11 +0900409 GET /groups/?query=<query>&limit=25&start=50 HTTP/1.0
Edwin Kempin6cfbb292017-01-04 09:40:50 +0100410----
411
412[[group-query-options]]
413==== Group Options
414Additional fields can be obtained by adding `o` parameters. Each option
415requires more lookups and slows down the query response time to the
416client so they are generally disabled by default. The supported fields
417are described in the context of the link:#group-options[List Groups]
418REST endpoint.
419
Edwin Kempina5cc1122013-02-11 09:26:20 +0100420[[get-group]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800421=== Get Group
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800422--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100423'GET /groups/link:#group-id[\{group-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800424--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100425
Edwin Kempina5cc1122013-02-11 09:26:20 +0100426Retrieves a group.
427
428.Request
429----
430 GET /groups/6a1e70e1a88782771a91808c8af9bbb7a9871389 HTTP/1.0
431----
432
433As response a link:#group-info[GroupInfo] entity is returned that
434describes the group.
435
436.Response
437----
438 HTTP/1.1 200 OK
439 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900440 Content-Type: application/json; charset=UTF-8
Edwin Kempina5cc1122013-02-11 09:26:20 +0100441
442 )]}'
443 {
Edwin Kempina5cc1122013-02-11 09:26:20 +0100444 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
445 "name": "Administrators",
446 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
447 "options": {
Edwin Kempina5cc1122013-02-11 09:26:20 +0100448 },
449 "description": "Gerrit Site Administrators",
450 "group_id": 1,
Edwin Kempinc6993fb2013-02-11 12:39:13 +0100451 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200452 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
453 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempina5cc1122013-02-11 09:26:20 +0100454 }
455----
456
Edwin Kempin578fff72013-02-11 08:08:27 +0100457[[create-group]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800458=== Create Group
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800459--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100460'PUT /groups/link:#group-name[\{group-name\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800461--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100462
Edwin Kempin578fff72013-02-11 08:08:27 +0100463Creates a new Gerrit internal group.
464
465In the request body additional data for the group can be provided as
466link:#group-input[GroupInput].
467
468.Request
469----
470 PUT /groups/MyProject-Committers HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900471 Content-Type: application/json; charset=UTF-8
Edwin Kempin578fff72013-02-11 08:08:27 +0100472
473 {
474 "description": "contains all committers for MyProject",
475 "visible_to_all": true,
Edwin Kempinc6993fb2013-02-11 12:39:13 +0100476 "owner": "MyProject-Owners",
Edwin Kempin578fff72013-02-11 08:08:27 +0100477 "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
478 }
479----
480
481As response the link:#group-info[GroupInfo] entity is returned that
482describes the created group.
483
484.Response
485----
486 HTTP/1.1 201 Created
487 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900488 Content-Type: application/json; charset=UTF-8
Edwin Kempin578fff72013-02-11 08:08:27 +0100489
490 )]}'
491 {
Edwin Kempin578fff72013-02-11 08:08:27 +0100492 "id": "9999c971bb4ab872aab759d8c49833ee6b9ff320",
493 "name": "MyProject-Committers",
494 "url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
495 "options": {
Edwin Kempin578fff72013-02-11 08:08:27 +0100496 "visible_to_all": true
497 },
498 "description":"contains all committers for MyProject",
499 "group_id": 551,
Edwin Kempinc6993fb2013-02-11 12:39:13 +0100500 "owner": "MyProject-Owners",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200501 "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
502 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin578fff72013-02-11 08:08:27 +0100503 }
504----
505
David Pursehouse666b34d2019-09-09 09:08:56 +0900506If the group creation fails because the name is already in use, or the
507UUID was specified and the UUID is already in use, the response is
508"`409 Conflict`".
Edwin Kempin0aa27102013-02-27 16:44:16 +0100509
Edwin Kempinabaab5462013-02-11 15:30:19 +0100510[[get-group-detail]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800511=== Get Group Detail
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800512--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100513'GET /groups/link:#group-id[\{group-id\}]/detail'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800514--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100515
Edwin Kempinabaab5462013-02-11 15:30:19 +0100516Retrieves a group with the direct link:#members[members] and the
517directly link:#includes[included groups].
518
519.Request
520----
521 GET /groups/6a1e70e1a88782771a91808c8af9bbb7a9871389/detail HTTP/1.0
522----
523
524As response a link:#group-info[GroupInfo] entity is returned that
525describes the group.
526
527.Response
528----
529 HTTP/1.1 200 OK
530 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900531 Content-Type: application/json; charset=UTF-8
Edwin Kempinabaab5462013-02-11 15:30:19 +0100532
533 )]}'
534 {
Edwin Kempinabaab5462013-02-11 15:30:19 +0100535 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
536 "name": "Administrators",
537 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
538 "options": {
539 },
540 "description": "Gerrit Site Administrators",
541 "group_id": 1,
542 "owner": "Administrators",
543 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200544 "created_on": "2013-02-01 09:59:32.126000000",
Edwin Kempinabaab5462013-02-11 15:30:19 +0100545 "members": [
546 {
Edwin Kempin51284e62013-03-05 15:26:41 +0100547 "_account_id": 1000097,
548 "name": "Jane Roe",
James Ring8e342722013-05-01 01:40:53 -0700549 "email": "jane.roe@example.com",
550 "username": "jane"
Edwin Kempinabaab5462013-02-11 15:30:19 +0100551 },
552 {
Edwin Kempin51284e62013-03-05 15:26:41 +0100553 "_account_id": 1000096,
554 "name": "John Doe",
555 "email": "john.doe@example.com"
James Ring8e342722013-05-01 01:40:53 -0700556 "username": "john"
Edwin Kempinabaab5462013-02-11 15:30:19 +0100557 }
558 ],
559 "includes": []
560 }
561----
562
Edwin Kempin1461c222013-02-11 08:41:08 +0100563[[get-group-name]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800564=== Get Group Name
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800565--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100566'GET /groups/link:#group-id[\{group-id\}]/name'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800567--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100568
Edwin Kempin1461c222013-02-11 08:41:08 +0100569Retrieves the name of a group.
570
571.Request
572----
573 GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/name HTTP/1.0
574----
575
576.Response
577----
578 HTTP/1.1 200 OK
579 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900580 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100581
582 )]}'
583 "MyProject-Committers"
584----
585
586[[rename-group]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800587=== Rename Group
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800588--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100589'PUT /groups/link:#group-id[\{group-id\}]/name'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800590--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100591
Edwin Kempin1461c222013-02-11 08:41:08 +0100592Renames a Gerrit internal group.
593
594The new group name must be provided in the request body.
595
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500596This endpoint is only allowed for Gerrit internal groups; attempting to call on a
597non-internal group will return 405 Method Not Allowed.
598
Edwin Kempin1461c222013-02-11 08:41:08 +0100599.Request
600----
601 PUT /groups/MyProject-Committers/name HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900602 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100603
604 {
605 "name": "My-Project-Committers"
606 }
607----
608
609As response the new group name is returned.
610
611.Response
612----
613 HTTP/1.1 200 OK
614 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900615 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100616
617 )]}'
618 "My-Project-Committers"
619----
620
Edwin Kempin0aa27102013-02-27 16:44:16 +0100621If renaming the group fails because the new name is already in use the
622response is "`409 Conflict`".
623
Edwin Kempin1461c222013-02-11 08:41:08 +0100624[[get-group-description]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800625=== Get Group Description
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800626--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100627'GET /groups/link:#group-id[\{group-id\}]/description'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800628--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100629
Edwin Kempin1461c222013-02-11 08:41:08 +0100630Retrieves the description of a group.
631
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500632This endpoint is only allowed for Gerrit internal groups; attempting to call on a
633non-internal group will return 405 Method Not Allowed.
634
Edwin Kempin1461c222013-02-11 08:41:08 +0100635.Request
636----
637 GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
638----
639
640.Response
641----
642 HTTP/1.1 200 OK
643 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900644 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100645
646 )]}'
647 "contains all committers for MyProject"
648----
649
Edwin Kempinefec4492013-02-22 10:09:23 +0100650If the group does not have a description an empty string is returned.
651
Edwin Kempin1461c222013-02-11 08:41:08 +0100652[[set-group-description]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800653=== Set Group Description
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800654--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100655'PUT /groups/link:#group-id[\{group-id\}]/description'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800656--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100657
Edwin Kempin1461c222013-02-11 08:41:08 +0100658Sets the description of a Gerrit internal group.
659
660The new group description must be provided in the request body.
661
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500662This endpoint is only allowed for Gerrit internal groups; attempting to call on a
663non-internal group will return 405 Method Not Allowed.
664
Edwin Kempin1461c222013-02-11 08:41:08 +0100665.Request
666----
667 PUT /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900668 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100669
670 {
671 "description": "The committers of MyProject."
672 }
673----
674
675As response the new group description is returned.
676
677.Response
678----
679 HTTP/1.1 200 OK
680 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900681 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100682
683 )]}'
684 "The committers of MyProject."
685----
686
Edwin Kempin114ab162013-02-28 09:25:37 +0100687If the description was deleted the response is "`204 No Content`".
688
Edwin Kempin1461c222013-02-11 08:41:08 +0100689[[delete-group-description]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800690=== Delete Group Description
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800691--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100692'DELETE /groups/link:#group-id[\{group-id\}]/description'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800693--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100694
Edwin Kempin1461c222013-02-11 08:41:08 +0100695Deletes the description of a Gerrit internal group.
696
697.Request
698----
699 DELETE /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
700----
701
702.Response
703----
704 HTTP/1.1 204 No Content
705----
706
707[[get-group-options]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800708=== Get Group Options
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800709--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100710'GET /groups/link:#group-id[\{group-id\}]/options'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800711--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100712
Edwin Kempin1461c222013-02-11 08:41:08 +0100713Retrieves the options of a group.
714
715.Request
716----
717 GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/options HTTP/1.0
718----
719
720As response a link:#group-options-info[GroupOptionsInfo] entity is
721returned that describes the options of the group.
722
723.Response
724----
725 HTTP/1.1 200 OK
726 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900727 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100728
729 )]}'
730 {
Edwin Kempin1461c222013-02-11 08:41:08 +0100731 "visible_to_all": true
732 }
733----
734
735[[set-group-options]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800736=== Set Group Options
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800737--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100738'PUT /groups/link:#group-id[\{group-id\}]/options'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800739--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100740
Edwin Kempin1461c222013-02-11 08:41:08 +0100741Sets the options of a Gerrit internal group.
742
743The new group options must be provided in the request body as a
744link:#group-options-input[GroupOptionsInput] entity.
745
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500746This endpoint is only allowed for Gerrit internal groups; attempting to call on a
747non-internal group will return 405 Method Not Allowed.
748
Edwin Kempin1461c222013-02-11 08:41:08 +0100749.Request
750----
751 PUT /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/options HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900752 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100753
754 {
755 "visible_to_all": true
756 }
757----
758
759As response the new group options are returned as a
760link:#group-options-info[GroupOptionsInfo] entity.
761
762.Response
763----
764 HTTP/1.1 200 OK
765 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900766 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100767
768 )]}'
769 {
Edwin Kempin1461c222013-02-11 08:41:08 +0100770 "visible_to_all": true
771 }
772----
773
774[[get-group-owner]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800775=== Get Group Owner
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800776--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100777'GET /groups/link:#group-id[\{group-id\}]/owner'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800778--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100779
Edwin Kempin1461c222013-02-11 08:41:08 +0100780Retrieves the owner group of a Gerrit internal group.
781
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500782This endpoint is only allowed for Gerrit internal groups; attempting to call on a
783non-internal group will return 405 Method Not Allowed.
784
Edwin Kempin1461c222013-02-11 08:41:08 +0100785.Request
786----
787 GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/owner HTTP/1.0
788----
789
790As response a link:#group-info[GroupInfo] entity is returned that
791describes the owner group.
792
793.Response
794----
795 HTTP/1.1 200 OK
796 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900797 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100798
799 )]}'
800 {
Edwin Kempin1461c222013-02-11 08:41:08 +0100801 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
802 "name": "Administrators",
803 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
804 "options": {
Edwin Kempin1461c222013-02-11 08:41:08 +0100805 },
806 "description": "Gerrit Site Administrators",
807 "group_id": 1,
Edwin Kempinc6993fb2013-02-11 12:39:13 +0100808 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200809 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
810 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin1461c222013-02-11 08:41:08 +0100811 }
812----
813
814[[set-group-owner]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800815=== Set Group Owner
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800816--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100817'PUT /groups/link:#group-id[\{group-id\}]/owner'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800818--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100819
Edwin Kempin1461c222013-02-11 08:41:08 +0100820Sets the owner group of a Gerrit internal group.
821
822The new owner group must be provided in the request body.
823
Edwin Kempinc9770902013-02-15 15:38:03 +0100824The new owner can be specified by name, by group UUID or by the legacy
825numeric group ID.
826
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500827This endpoint is only allowed for Gerrit internal groups; attempting to call on a
828non-internal group will return 405 Method Not Allowed.
829
Edwin Kempin1461c222013-02-11 08:41:08 +0100830.Request
831----
Paladox nonef6e83012017-06-18 21:17:57 +0000832 PUT /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/owner HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900833 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100834
835 {
836 "owner": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
837 }
838----
839
840As response a link:#group-info[GroupInfo] entity is returned that
841describes the new owner group.
842
843.Response
844----
845 HTTP/1.1 200 OK
846 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900847 Content-Type: application/json; charset=UTF-8
Edwin Kempin1461c222013-02-11 08:41:08 +0100848
849 )]}'
850 {
Edwin Kempin1461c222013-02-11 08:41:08 +0100851 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
852 "name": "Administrators",
853 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
854 "options": {
Edwin Kempin1461c222013-02-11 08:41:08 +0100855 },
856 "description": "Gerrit Site Administrators",
857 "group_id": 1,
Edwin Kempinc6993fb2013-02-11 12:39:13 +0100858 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200859 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
860 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin1461c222013-02-11 08:41:08 +0100861 }
862----
863
Edwin Kempinfc3f8322015-07-03 13:34:19 +0200864[[get-audit-log]]
865=== Get Audit Log
866--
867'GET /groups/link:#group-id[\{group-id\}]/log.audit'
868--
869
870Gets the audit log of a Gerrit internal group.
871
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500872This endpoint is only allowed for Gerrit internal groups; attempting to call on a
873non-internal group will return 405 Method Not Allowed.
874
Edwin Kempinfc3f8322015-07-03 13:34:19 +0200875.Request
876----
877 GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/log.audit HTTP/1.0
878----
879
880As response a list of link:#group-audit-event-info[GroupAuditEventInfo]
881entities is returned that describes the audit events of the group. The
882returned audit events are sorted by date in reverse order so that the
883newest audit event comes first.
884
885.Response
886----
887 HTTP/1.1 200 OK
888 Content-Disposition: attachment
889 Content-Type: application/json; charset=UTF-8
890
891 )]}'
892 [
893 {
894 "member": {
895 "url": "#/admin/groups/uuid-fdda826a0815859ab48d22a05a43472f0f55f89a",
896 "options": {},
897 "group_id": 3,
898 "owner": "Administrators",
899 "owner_id": "e56678641565e7f59dd5c6878f5bcbc842bf150a",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200900 "created_on": "2013-02-01 09:59:32.126000000",
Edwin Kempinfc3f8322015-07-03 13:34:19 +0200901 "id": "fdda826a0815859ab48d22a05a43472f0f55f89a",
902 "name": "MyGroup"
903 },
904 "type": "REMOVE_GROUP",
905 "user": {
906 "_account_id": 1000000,
907 "name": "Administrator",
908 "email": "admin@example.com",
909 "username": "admin"
910 },
911 "date": "2015-07-03 09:22:26.348000000"
912 },
913 {
914 "member": {
915 "url": "#/admin/groups/uuid-fdda826a0815859ab48d22a05a43472f0f55f89a",
916 "options": {},
917 "group_id": 3,
918 "owner": "Administrators",
919 "owner_id": "e56678641565e7f59dd5c6878f5bcbc842bf150a",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +0200920 "created_on": "2013-02-01 09:59:32.126000000",
Edwin Kempinfc3f8322015-07-03 13:34:19 +0200921 "id": "fdda826a0815859ab48d22a05a43472f0f55f89a",
922 "name": "MyGroup"
923 },
924 "type": "ADD_GROUP",
925 "user": {
926 "_account_id": 1000000,
927 "name": "Administrator",
928 "email": "admin@example.com",
929 "username": "admin"
930 },
931 "date": "2015-07-03 08:43:36.592000000"
932 },
933 {
934 "member": {
935 "_account_id": 1000000,
936 "name": "Administrator",
937 "email": "admin@example.com",
938 "username": "admin"
939 },
940 "type": "ADD_USER",
941 "user": {
942 "_account_id": 1000001,
943 "name": "John Doe",
944 "email": "john.doe@example.com",
945 "username": "jdoe"
946 },
947 "date": "2015-07-01 13:36:36.602000000"
948 }
949 ]
950----
951
Edwin Kempin4550a252017-01-04 14:22:02 +0100952[[index-group]]
953=== Index Group
954--
955'POST /groups/link:#group-id[\{group-id\}]/index'
956--
957
958Adds or updates the internal group in the secondary index.
959
960.Request
961----
962 POST /groups/fdda826a0815859ab48d22a05a43472f0f55f89a/index HTTP/1.0
963----
964
965.Response
966----
967 HTTP/1.1 204 No Content
968----
969
Edwin Kempin578fff72013-02-11 08:08:27 +0100970[[group-member-endpoints]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800971== Group Member Endpoints
Edwin Kempin578fff72013-02-11 08:08:27 +0100972
Edwin Kempind0a63922013-01-23 16:32:59 +0100973[[group-members]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800974=== List Group Members
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800975--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100976'GET /groups/link:#group-id[\{group-id\}]/members/'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -0800977--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +0100978
Edwin Kempin2dc5edc2013-02-11 15:57:36 +0100979Lists the direct members of a Gerrit internal group.
Edwin Kempind0a63922013-01-23 16:32:59 +0100980
Edwin Kempin963dfd02013-02-27 12:39:32 +0100981As result a list of detailed link:rest-api-accounts.html#account-info[
982AccountInfo] entries is returned. The entries in the list are sorted by
983full name, preferred email and id.
Edwin Kempin4156d6e02013-02-04 15:10:39 +0100984
Dave Borowitzbf5efd52018-02-06 09:52:42 -0500985This endpoint is only allowed for Gerrit internal groups; attempting to call on a
986non-internal group will return 405 Method Not Allowed.
987
Edwin Kempin37440832013-02-06 11:36:00 +0100988.Request
Edwin Kempind0a63922013-01-23 16:32:59 +0100989----
990 GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/ HTTP/1.0
Edwin Kempin37440832013-02-06 11:36:00 +0100991----
Edwin Kempind0a63922013-01-23 16:32:59 +0100992
Edwin Kempin37440832013-02-06 11:36:00 +0100993.Response
994----
Edwin Kempind0a63922013-01-23 16:32:59 +0100995 HTTP/1.1 200 OK
996 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +0900997 Content-Type: application/json; charset=UTF-8
Edwin Kempind0a63922013-01-23 16:32:59 +0100998
999 )]}'
1000 [
1001 {
Edwin Kempin963dfd02013-02-27 12:39:32 +01001002 "_account_id": 1000097,
1003 "name": "Jane Roe",
James Ring8e342722013-05-01 01:40:53 -07001004 "email": "jane.roe@example.com",
1005 "username": "jane"
Edwin Kempind0a63922013-01-23 16:32:59 +01001006 },
1007 {
Edwin Kempin963dfd02013-02-27 12:39:32 +01001008 "_account_id": 1000096,
1009 "name": "John Doe",
James Ring8e342722013-05-01 01:40:53 -07001010 "email": "john.doe@example.com",
1011 "username": "john"
Edwin Kempind0a63922013-01-23 16:32:59 +01001012 }
1013 ]
1014----
1015
Edwin Kempina64c4b92013-01-23 11:30:40 +01001016.Get all members of the 'Administrators' group (normally group id = 1)
1017****
1018get::/groups/1/members/
1019****
1020
Edwin Kempind0a63922013-01-23 16:32:59 +01001021To resolve the included groups of a group recursively and to list all
1022members the parameter `recursive` can be set.
1023
Edwin Kempind54de1c2013-03-08 16:37:14 +01001024Members from included external groups and from included groups which
1025are not visible to the calling user are ignored.
1026
Edwin Kempin37440832013-02-06 11:36:00 +01001027.Request
Edwin Kempind0a63922013-01-23 16:32:59 +01001028----
1029 GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/?recursive HTTP/1.0
Edwin Kempin37440832013-02-06 11:36:00 +01001030----
Edwin Kempind0a63922013-01-23 16:32:59 +01001031
Edwin Kempin37440832013-02-06 11:36:00 +01001032.Response
1033----
Edwin Kempind0a63922013-01-23 16:32:59 +01001034 HTTP/1.1 200 OK
1035 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001036 Content-Type: application/json; charset=UTF-8
Edwin Kempind0a63922013-01-23 16:32:59 +01001037
1038 )]}'
1039 [
1040 {
Edwin Kempin3e22d482013-03-05 15:35:25 +01001041 "_account_id": 1000097,
1042 "name": "Jane Roe",
James Ring8e342722013-05-01 01:40:53 -07001043 "email": "jane.roe@example.com",
1044 "username": "jane"
Edwin Kempind0a63922013-01-23 16:32:59 +01001045 },
1046 {
Edwin Kempin3e22d482013-03-05 15:35:25 +01001047 "_account_id": 1000096,
1048 "name": "John Doe",
James Ring8e342722013-05-01 01:40:53 -07001049 "email": "john.doe@example.com",
1050 "username": "john"
Edwin Kempind0a63922013-01-23 16:32:59 +01001051 },
1052 {
Edwin Kempin3e22d482013-03-05 15:35:25 +01001053 "_account_id": 1000098,
1054 "name": "Richard Roe",
James Ring8e342722013-05-01 01:40:53 -07001055 "email": "richard.roe@example.com",
1056 "username": "rroe"
Edwin Kempind0a63922013-01-23 16:32:59 +01001057 }
1058 ]
1059----
1060
Edwin Kempina5cc1122013-02-11 09:26:20 +01001061[[get-group-member]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001062=== Get Group Member
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001063--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001064'GET /groups/link:#group-id[\{group-id\}]/members/link:rest-api-accounts.html#account-id[\{account-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001065--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001066
Edwin Kempina5cc1122013-02-11 09:26:20 +01001067Retrieves a group member.
1068
1069.Request
1070----
1071 GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/1000096 HTTP/1.0
1072----
1073
Edwin Kempin963dfd02013-02-27 12:39:32 +01001074As response a detailed link:rest-api-accounts.html#account-info[
1075AccountInfo] entity is returned that describes the group member.
Edwin Kempina5cc1122013-02-11 09:26:20 +01001076
1077.Response
1078----
1079 HTTP/1.1 200 OK
1080 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001081 Content-Type: application/json; charset=UTF-8
Edwin Kempina5cc1122013-02-11 09:26:20 +01001082
1083 )]}'
1084 {
Edwin Kempin963dfd02013-02-27 12:39:32 +01001085 "_account_id": 1000096,
1086 "name": "John Doe",
James Ring8e342722013-05-01 01:40:53 -07001087 "email": "john.doe@example.com",
1088 "username": "john"
Edwin Kempina5cc1122013-02-11 09:26:20 +01001089 }
1090----
1091
Edwin Kempina5d6ead2013-02-06 10:59:06 +01001092[[add-group-member]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001093=== Add Group Member
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001094--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001095'PUT /groups/link:#group-id[\{group-id\}]/members/link:rest-api-accounts.html#account-id[\{account-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001096--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001097
Edwin Kempina5d6ead2013-02-06 10:59:06 +01001098Adds a user as member to a Gerrit internal group.
1099
Dave Borowitzbf5efd52018-02-06 09:52:42 -05001100This endpoint is only allowed for Gerrit internal groups; attempting to call on a
1101non-internal group will return 405 Method Not Allowed.
1102
Edwin Kempina5d6ead2013-02-06 10:59:06 +01001103.Request
1104----
1105 PUT /groups/MyProject-Committers/members/John%20Doe HTTP/1.0
1106----
1107
Edwin Kempin963dfd02013-02-27 12:39:32 +01001108As response a detailed link:rest-api-accounts.html#account-info[
1109AccountInfo] entity is returned that describes the group member.
Edwin Kempina5d6ead2013-02-06 10:59:06 +01001110
1111.Response
1112----
1113 HTTP/1.1 201 Created
1114 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001115 Content-Type: application/json; charset=UTF-8
Edwin Kempina5d6ead2013-02-06 10:59:06 +01001116
1117 )]}'
1118 {
Edwin Kempin963dfd02013-02-27 12:39:32 +01001119 "_account_id": 1000037,
1120 "name": "John Doe",
James Ring8e342722013-05-01 01:40:53 -07001121 "email": "john.doe@example.com",
1122 "username": "john"
Edwin Kempina5d6ead2013-02-06 10:59:06 +01001123 }
1124----
1125
1126The request also succeeds if the user is already a member of this
1127group, but then the HTTP response code is `200 OK`.
1128
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001129=== Add Group Members
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001130--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001131'POST /groups/link:#group-id[\{group-id\}]/members'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001132--
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001133
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001134OR
1135
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001136--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001137'POST /groups/link:#group-id[\{group-id\}]/members.add'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001138--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001139
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001140Adds one or several users to a Gerrit internal group.
1141
1142The users to be added to the group must be provided in the request body
Sasa Zivkov737e0a32013-03-18 14:21:42 +01001143as a link:#members-input[MembersInput] entity.
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001144
1145.Request
1146----
1147 POST /groups/MyProject-Committers/members.add HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001148 Content-Type: application/json; charset=UTF-8
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001149
1150 {
Chris St. Pierreb39fb9e2013-08-06 15:55:00 -04001151 "members": [
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001152 "jane.roe@example.com",
1153 "john.doe@example.com"
Chris St. Pierreb39fb9e2013-08-06 15:55:00 -04001154 ]
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001155 }
1156----
1157
Edwin Kempin963dfd02013-02-27 12:39:32 +01001158As response a list of detailed link:rest-api-accounts.html#account-info[
1159AccountInfo] entities is returned that describes the group members that
Sasa Zivkov737e0a32013-03-18 14:21:42 +01001160were specified in the link:#members-input[MembersInput]. An
Edwin Kempin963dfd02013-02-27 12:39:32 +01001161link:rest-api-accounts.html#account-info[AccountInfo] entity
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001162is returned for each user specified in the input, independently of
1163whether the user was newly added to the group or whether the user was
1164already a member of the group.
1165
1166.Response
1167----
1168 HTTP/1.1 200 OK
1169 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001170 Content-Type: application/json; charset=UTF-8
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001171
1172 )]}'
1173 [
1174 {
Edwin Kempin963dfd02013-02-27 12:39:32 +01001175 "_account_id": 1000057,
1176 "name": "Jane Roe",
James Ring8e342722013-05-01 01:40:53 -07001177 "email": "jane.roe@example.com",
1178 "username": "jane"
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001179 },
1180 {
Edwin Kempin963dfd02013-02-27 12:39:32 +01001181 "_account_id": 1000037,
1182 "name": "John Doe",
James Ring8e342722013-05-01 01:40:53 -07001183 "email": "john.doe@example.com",
1184 "username": "john"
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001185 }
1186 ]
1187----
1188
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001189[[remove-group-member]]
1190=== Remove Group Member
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001191--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001192'DELETE /groups/link:#group-id[\{group-id\}]/members/link:rest-api-accounts.html#account-id[\{account-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001193--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001194
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001195Removes a user from a Gerrit internal group.
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001196
Dave Borowitzbf5efd52018-02-06 09:52:42 -05001197This endpoint is only allowed for Gerrit internal groups; attempting to call on a
1198non-internal group will return 405 Method Not Allowed.
1199
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001200.Request
1201----
1202 DELETE /groups/MyProject-Committers/members/John%20Doe HTTP/1.0
1203----
1204
1205.Response
1206----
1207 HTTP/1.1 204 No Content
1208----
1209
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001210[[remove-group-members]]
1211=== Remove Group Members
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001212--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001213'POST /groups/link:#group-id[\{group-id\}]/members.delete'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001214--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001215
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001216Removes one or several users from a Gerrit internal group.
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001217
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001218The users to be removed from the group must be provided in the request
Sasa Zivkov737e0a32013-03-18 14:21:42 +01001219body as a link:#members-input[MembersInput] entity.
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001220
1221.Request
1222----
1223 POST /groups/MyProject-Committers/members.delete HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001224 Content-Type: application/json; charset=UTF-8
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001225
1226 {
Chris St. Pierreb39fb9e2013-08-06 15:55:00 -04001227 "members": [
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001228 "jane.roe@example.com",
1229 "john.doe@example.com"
Chris St. Pierreb39fb9e2013-08-06 15:55:00 -04001230 ]
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001231 }
1232----
1233
1234.Response
1235----
1236 HTTP/1.1 204 No Content
1237----
1238
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001239[[subgroup-endpoints]]
1240== Subgroup Endpoints
Edwin Kempin578fff72013-02-11 08:08:27 +01001241
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001242[[list-subgroups]]
1243=== List Subgroups
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001244--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001245'GET /groups/link:#group-id[\{group-id\}]/groups/'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001246--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001247
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001248Lists the direct subgroups of a group.
Edwin Kempin578fff72013-02-11 08:08:27 +01001249
1250As result a list of link:#group-info[GroupInfo] entries is returned.
1251The entries in the list are sorted by group name and UUID.
1252
Dave Borowitzbf5efd52018-02-06 09:52:42 -05001253This endpoint is only allowed for Gerrit internal groups; attempting to call on a
1254non-internal group will return 405 Method Not Allowed.
1255
Edwin Kempin578fff72013-02-11 08:08:27 +01001256.Request
1257----
1258 GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/ HTTP/1.0
1259----
1260
1261.Response
1262----
1263 HTTP/1.1 200 OK
1264 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001265 Content-Type: application/json; charset=UTF-8
Edwin Kempin578fff72013-02-11 08:08:27 +01001266
1267 )]}'
1268 [
1269 {
Edwin Kempin578fff72013-02-11 08:08:27 +01001270 "id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
1271 "name": "MyProject-Verifiers",
Edwin Kempine05c9642013-02-11 09:36:21 +01001272 "url": "#/admin/groups/uuid-7ca042f4d5847936fcb90ca91057673157fd06fc",
1273 "options": {
Edwin Kempine05c9642013-02-11 09:36:21 +01001274 },
Edwin Kempin578fff72013-02-11 08:08:27 +01001275 "group_id": 38,
Edwin Kempinc6993fb2013-02-11 12:39:13 +01001276 "owner": "MyProject-Verifiers",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +02001277 "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
1278 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin578fff72013-02-11 08:08:27 +01001279 }
1280 ]
1281----
1282
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001283[[get-subgroup]]
1284=== Get Subgroup
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001285--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001286'GET /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001287--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001288
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001289Retrieves a subgroup.
Edwin Kempina5cc1122013-02-11 09:26:20 +01001290
1291.Request
1292----
1293 GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/7ca042f4d5847936fcb90ca91057673157fd06fc HTTP/1.0
1294----
1295
1296As response a link:#group-info[GroupInfo] entity is returned that
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001297describes the subgroup.
Edwin Kempina5cc1122013-02-11 09:26:20 +01001298
1299.Response
1300----
1301 HTTP/1.1 200 OK
1302 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001303 Content-Type: application/json; charset=UTF-8
Edwin Kempina5cc1122013-02-11 09:26:20 +01001304
1305 )]}'
1306 {
Edwin Kempina5cc1122013-02-11 09:26:20 +01001307 "id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
1308 "name": "MyProject-Verifiers",
1309 "url": "#/admin/groups/uuid-7ca042f4d5847936fcb90ca91057673157fd06fc",
1310 "options": {
Edwin Kempina5cc1122013-02-11 09:26:20 +01001311 },
1312 "group_id": 38,
Edwin Kempinc6993fb2013-02-11 12:39:13 +01001313 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +02001314 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
1315 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempina5cc1122013-02-11 09:26:20 +01001316 }
1317----
1318
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001319[[add-subgroup]]
1320=== Add Subgroup
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001321--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001322'PUT /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001323--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001324
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001325Adds an internal or external group as subgroup to a Gerrit internal group.
Dariusz Lukszaccfa6492013-06-07 11:07:38 +02001326External groups must be specified using the UUID.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001327
Dave Borowitzbf5efd52018-02-06 09:52:42 -05001328This endpoint is only allowed for Gerrit internal groups; attempting to call on a
1329non-internal group will return 405 Method Not Allowed.
1330
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001331.Request
1332----
1333 PUT /groups/MyProject-Committers/groups/MyGroup HTTP/1.0
1334----
1335
1336As response a link:#group-info[GroupInfo] entity is returned that
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001337describes the subgroup.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001338
1339.Response
1340----
1341 HTTP/1.1 201 Created
1342 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001343 Content-Type: application/json; charset=UTF-8
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001344
1345 )]}'
1346 {
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001347 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
1348 "name": "MyGroup",
1349 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
1350 "options": {
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001351 },
1352 "group_id": 8,
Edwin Kempinc6993fb2013-02-11 12:39:13 +01001353 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +02001354 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
1355 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001356 }
1357----
1358
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001359The request also succeeds if the group is already a subgroup of this
1360group.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001361
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001362[[add-subgroups]]
1363=== Add Subgroups
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001364--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001365'POST /groups/link:#group-id[\{group-id\}]/groups'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001366--
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001367
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001368OR
1369
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001370--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001371'POST /groups/link:#group-id[\{group-id\}]/groups.add'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001372--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001373
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001374Adds one or several groups as subgroups to a Gerrit internal group.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001375
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001376The subgroups to be added must be provided in the request body as a
1377link:#groups-input[GroupsInput] entity.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001378
1379.Request
1380----
1381 POST /groups/MyProject-Committers/groups.add HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001382 Content-Type: application/json; charset=UTF-8
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001383
1384 {
Dave Borowitzd2b92172014-04-01 11:15:18 -07001385 "groups": [
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001386 "MyGroup",
1387 "MyOtherGroup"
Dave Borowitzd2b92172014-04-01 11:15:18 -07001388 ]
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001389 }
1390----
1391
1392As response a list of link:#group-info[GroupInfo] entities is
1393returned that describes the groups that were specified in the
1394link:#groups-input[GroupsInput]. A link:#group-info[GroupInfo] entity
1395is returned for each group specified in the input, independently of
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001396whether the group was newly added as subgroup or whether the
1397group was already a subgroup of the group.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001398
1399.Response
1400----
1401 HTTP/1.1 200 OK
1402 Content-Disposition: attachment
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001403 Content-Type: application/json; charset=UTF-8
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001404
1405 )]}'
1406 [
1407 {
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001408 "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
1409 "name": "MyGroup",
1410 "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
1411 "options": {
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001412 },
1413 "group_id": 8,
Edwin Kempinc6993fb2013-02-11 12:39:13 +01001414 "owner": "Administrators",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +02001415 "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
1416 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001417 },
1418 {
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001419 "id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
1420 "name": "MyOtherGroup",
1421 "url": "#/admin/groups/uuid-5057f3cbd3519d6ab69364429a89ffdffba50f73",
1422 "options": {
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001423 },
1424 "group_id": 10,
Edwin Kempinc6993fb2013-02-11 12:39:13 +01001425 "owner": "MyOtherGroup",
Alice Kober-Sotzek23249272017-06-23 10:29:32 +02001426 "owner_id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
1427 "created_on": "2013-02-01 09:59:32.126000000"
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001428 }
1429 ]
1430----
1431
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001432[[remove-subgroup]]
1433=== Remove Subgroup
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001434--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001435'DELETE /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001436--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001437
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001438Removes a subgroup from a Gerrit internal group.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001439
Dave Borowitzbf5efd52018-02-06 09:52:42 -05001440This endpoint is only allowed for Gerrit internal groups; attempting to call on a
1441non-internal group will return 405 Method Not Allowed.
1442
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001443.Request
1444----
1445 DELETE /groups/MyProject-Committers/groups/MyGroup HTTP/1.0
1446----
1447
1448.Response
1449----
1450 HTTP/1.1 204 No Content
1451----
1452
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001453[[remove-subgroups]]
1454=== Remove Subgroups
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001455--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001456'POST /groups/link:#group-id[\{group-id\}]/groups.delete'
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08001457--
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001458
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001459Removes one or several subgroups from a Gerrit internal group.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001460
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001461The subgroups to be removed must be provided in the request body as a
1462link:#groups-input[GroupsInput] entity.
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001463
1464.Request
1465----
1466 POST /groups/MyProject-Committers/groups.delete HTTP/1.0
David Pursehouse56bf1cb2015-01-06 15:44:00 +09001467 Content-Type: application/json; charset=UTF-8
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001468
1469 {
Edwin Kempin4b77e602014-04-18 08:54:36 +02001470 "groups": [
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001471 "MyGroup",
1472 "MyOtherGroup"
Dave Borowitzd2b92172014-04-01 11:15:18 -07001473 ]
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001474 }
1475----
1476
1477.Response
1478----
1479 HTTP/1.1 204 No Content
1480----
1481
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001482
Edwin Kempin34d83352013-02-06 10:40:17 +01001483[[ids]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001484== IDs
Edwin Kempin34d83352013-02-06 10:40:17 +01001485
Edwin Kempin2689e3d2013-02-07 15:52:36 +01001486[[group-id]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001487=== \{group-id\}
Edwin Kempin34d83352013-02-06 10:40:17 +01001488Identifier for a group.
1489
1490This can be:
1491
1492* the UUID of the group
1493* the legacy numeric ID of the group
1494* the name of the group if it is unique
1495
Edwin Kempin50d3d9b2013-03-06 16:38:26 +01001496[[group-name]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001497=== \{group-name\}
Edwin Kempin34d83352013-02-06 10:40:17 +01001498Group name that uniquely identifies one group.
1499
1500
Edwin Kempin987d5432013-02-04 10:20:44 +01001501[[json-entities]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001502== JSON Entities
Edwin Kempin987d5432013-02-04 10:20:44 +01001503
Edwin Kempinfc3f8322015-07-03 13:34:19 +02001504[[group-audit-event-info]]
1505=== GroupAuditEventInfo
1506The `GroupAuditEventInfo` entity contains information about an audit
1507event of a group.
1508
1509[options="header",cols="1,6"]
1510|======================
1511|Field Name|Description
1512|`member` |
1513The group member that is added/removed. If `type` is `ADD_USER` or
1514`REMOVE_USER` the member is returned as detailed
1515link:rest-api-accounts.html#account-info[AccountInfo] entity, if `type`
1516is `ADD_GROUP` or `REMOVE_GROUP` the member is returned as
Changcheng Xiao219e3c52018-02-27 09:53:37 +01001517link:#group-info[GroupInfo] entity. Note that the `name` in
1518link:#group-info[GroupInfo] will not be set if the member group is not
1519available.
Edwin Kempinfc3f8322015-07-03 13:34:19 +02001520|`type` |
1521The event type, can be: `ADD_USER`, `REMOVE_USER`, `ADD_GROUP` or
1522`REMOVE_GROUP`.
1523
1524`ADD_USER`: A user was added as member to the group.
1525
1526`REMOVE_USER`: A user member was removed from the group.
1527
1528`ADD_GROUP`: A group was included as member in the group.
1529
1530`REMOVE_GROUP`: An included group was removed from the group.
1531|`user` |
1532The user that did the add/remove as detailed
1533link:rest-api-accounts.html#account-info[AccountInfo] entity.
1534|`date` |
1535The timestamp of the event.
1536|======================
1537
Edwin Kempin987d5432013-02-04 10:20:44 +01001538[[group-info]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001539=== GroupInfo
Edwin Kempin987d5432013-02-04 10:20:44 +01001540The `GroupInfo` entity contains information about a group. This can be
1541a Gerrit internal group, or an external group that is known to Gerrit.
1542
David Pursehouseae367192014-11-25 17:24:47 +09001543[options="header",cols="1,^1,5"]
Edwin Kempin987d5432013-02-04 10:20:44 +01001544|===========================
1545|Field Name ||Description
Edwin Kempin987d5432013-02-04 10:20:44 +01001546|`id` ||The URL encoded UUID of the group.
Edwin Kempin5b591d12013-03-08 09:18:35 +01001547|`name` |
Edwin Kempin219e7972018-03-27 09:24:54 +02001548optional, not set if returned in a map where the group name is used as map key|
1549The name of the group. +
1550For external groups the group name is missing if there is no group
1551backend that can resolve the group UUID. E.g. this can happen when a
1552plugin that provided a group backend was uninstalled.
Edwin Kempin987d5432013-02-04 10:20:44 +01001553|`url` |optional|
1554URL to information about the group. Typically a URL to a web page that
1555permits users to apply to join the group, or manage their membership.
1556|`options` ||link:#group-options-info[Options of the group]
1557|`description` |only for internal groups|The description of the group.
1558|`group_id` |only for internal groups|The numeric ID of the group.
Edwin Kempin6a628e12017-11-13 11:13:27 +01001559|`owner` |only for internal groups|The name of the owner group.
1560|`owner_id` |only for internal groups|The URL encoded UUID of the owner group.
Alice Kober-Sotzek23249272017-06-23 10:29:32 +02001561|`created_on` |only for internal groups|The
1562link:rest-api.html#timestamp[timestamp] of when the group was created.
Edwin Kempinfadf3632017-01-03 15:16:17 +01001563|`_more_groups`|optional, only for internal groups, not set if `false`|
1564Whether the query would deliver more results if not limited. +
1565Only set on the last group that is returned by a
1566link:#query-groups[group query].
Edwin Kempinabaab5462013-02-11 15:30:19 +01001567|`members` |optional, only for internal groups|
1568A list of link:rest-api-accounts.html#account-info[AccountInfo]
1569entities describing the direct members. +
1570Only set if link:#members[members] are requested.
1571|`includes` |optional, only for internal groups|
Alice Kober-Sotzek8a9d8a42017-08-23 16:47:46 +02001572A list of link:#group-info[GroupInfo] entities describing the direct
1573subgroups. +
1574Only set if link:#includes[subgroups] are requested.
Edwin Kempin987d5432013-02-04 10:20:44 +01001575|===========================
1576
Edwin Kempinc42abb92013-02-04 14:52:41 +01001577The type of a group can be deduced from the group's UUID:
Edwin Kempinc42abb92013-02-04 14:52:41 +01001578|============
1579|UUID matches "^[0-9a-f]\{40\}$"|Gerrit internal group
1580|UUID starts with "global:"|Gerrit system group
1581|UUID starts with "ldap:"|LDAP group
1582|UUID starts with "<prefix>:"|other external group
1583|============
1584
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001585[[group-input]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001586=== GroupInput
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001587The 'GroupInput' entity contains information for the creation of
1588a new internal group.
1589
David Pursehouseae367192014-11-25 17:24:47 +09001590[options="header",cols="1,^1,5"]
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001591|===========================
1592|Field Name ||Description
1593|`name` |optional|The name of the group (not encoded). +
1594If set, must match the group name in the URL.
David Pursehouse666b34d2019-09-09 09:08:56 +09001595|`uuid` |optional|The UUID of the group.
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001596|`description` |optional|The description of the group.
1597|`visible_to_all`|optional|
1598Whether the group is visible to all registered users. +
1599`false` if not set.
Yuxuan 'fishy' Wang578eb502016-08-12 12:02:55 -07001600|`owner_id` |optional|The URL encoded ID of the owner group. +
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001601This can be a group UUID, a legacy numeric group ID or a unique group
1602name. +
1603If not set, the new group will be self-owned.
Yuxuan 'fishy' Wang578eb502016-08-12 12:02:55 -07001604|`members` |optional|The initial members in a list of +
Edwin Kempinc6d615a2016-12-01 14:49:31 +01001605link:rest-api-accounts.html#account-id[account ids].
Edwin Kempinaa266ff2013-02-05 12:41:09 +01001606|===========================
1607
Edwin Kempin987d5432013-02-04 10:20:44 +01001608[[group-options-info]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001609=== GroupOptionsInfo
Edwin Kempin987d5432013-02-04 10:20:44 +01001610Options of the group.
1611
David Pursehouseae367192014-11-25 17:24:47 +09001612[options="header",cols="1,^1,5"]
Edwin Kempinf04fc9c2013-02-05 14:09:45 +01001613|=============================
1614|Field Name ||Description
Edwin Kempinf04fc9c2013-02-05 14:09:45 +01001615|`visible_to_all`|not set if `false`|
Edwin Kempin987d5432013-02-04 10:20:44 +01001616Whether the group is visible to all registered users.
Edwin Kempinf04fc9c2013-02-05 14:09:45 +01001617|=============================
Edwin Kempin987d5432013-02-04 10:20:44 +01001618
Edwin Kempin1461c222013-02-11 08:41:08 +01001619[[group-options-input]]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001620=== GroupOptionsInput
Edwin Kempin1461c222013-02-11 08:41:08 +01001621New options for a group.
1622
David Pursehouseae367192014-11-25 17:24:47 +09001623[options="header",cols="1,^1,5"]
Edwin Kempin1461c222013-02-11 08:41:08 +01001624|=============================
1625|Field Name ||Description
1626|`visible_to_all`|not set if `false`|
1627Whether the group is visible to all registered users.
1628|=============================
1629
Edwin Kempin521c1242015-01-23 12:44:44 +01001630[[groups-input]]
1631=== GroupsInput
1632The `GroupsInput` entity contains information about groups that should
1633be included into a group or that should be deleted from a group.
1634
1635[options="header",cols="1,^1,5"]
1636|==========================
1637|Field Name ||Description
1638|`_one_group` |optional|
1639The link:#group-id[id] of one group that should be included or deleted.
1640|`groups` |optional|
1641A list of link:#group-id[group ids] that identify the groups that
1642should be included or deleted.
1643|==========================
1644
Sasa Zivkov737e0a32013-03-18 14:21:42 +01001645[[members-input]]
David Pursehouseb10c2662016-12-06 08:41:33 +09001646=== MembersInput
Sasa Zivkov737e0a32013-03-18 14:21:42 +01001647The `MembersInput` entity contains information about accounts that should
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001648be added as members to a group or that should be deleted from the group.
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001649
David Pursehouseae367192014-11-25 17:24:47 +09001650[options="header",cols="1,^1,5"]
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001651|==========================
1652|Field Name ||Description
1653|`_one_member`|optional|
Edwin Kempinc6d615a2016-12-01 14:49:31 +01001654The link:rest-api-accounts.html#account-id[id] of one account that
Edwin Kempinacbdfd32013-02-07 12:38:53 +01001655should be added or deleted.
Edwin Kempinc6d615a2016-12-01 14:49:31 +01001656|`members` |optional|
1657A list of link:rest-api-accounts.html#account-id[account ids] that
1658identify the accounts that should be added or deleted.
Edwin Kempin2cdef5f2013-02-06 16:50:15 +01001659|==========================
1660
1661
Edwin Kempind0a63922013-01-23 16:32:59 +01001662GERRIT
1663------
1664Part of link:index.html[Gerrit Code Review]
Yuxuan 'fishy' Wang99cb68d2013-10-31 17:26:00 -07001665
1666SEARCHBOX
1667---------