737e0a334a
Using plural for MembersInput makes it consistent with the usage of the plural in the GroupsInput name. Change-Id: Id453267cfc79c3983a8fcb02349303d2b14a26df Signed-off-by: Sasa Zivkov <sasa.zivkov@sap.com>
1230 lines
29 KiB
Plaintext
1230 lines
29 KiB
Plaintext
Gerrit Code Review - /groups/ REST API
|
|
======================================
|
|
|
|
This page describes the group related REST endpoints.
|
|
Please also take note of the general information on the
|
|
link:rest-api.html[REST API].
|
|
|
|
[[group-endpoints]]
|
|
Group Endpoints
|
|
---------------
|
|
|
|
[[list-groups]]
|
|
List Groups
|
|
~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/'
|
|
|
|
Lists the groups accessible by the caller. This is the same as
|
|
using the link:cmd-ls-groups.html[ls-groups] command over SSH,
|
|
and accepts the same options as query parameters.
|
|
|
|
As result a map is returned that maps the group names to
|
|
link:#group-info[GroupInfo] entries. The entries in the map are sorted
|
|
by group name.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/ HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"Administrators": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"description": "Gerrit Site Administrators",
|
|
"group_id": 1,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
},
|
|
"Anonymous Users": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "global%3AAnonymous-Users",
|
|
"url": "#/admin/groups/uuid-global%3AAnonymous-Users",
|
|
"options": {
|
|
},
|
|
"description": "Any user, signed-in or not",
|
|
"group_id": 2,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
},
|
|
"MyProject_Committers": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
|
|
"url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
|
|
"options": {
|
|
"visible_to_all": true,
|
|
},
|
|
"group_id": 6,
|
|
"owner": "MyProject_Committers",
|
|
"owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7"
|
|
},
|
|
"Non-Interactive Users": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
|
|
"url": "#/admin/groups/uuid-5057f3cbd3519d6ab69364429a89ffdffba50f73",
|
|
"options": {
|
|
},
|
|
"description": "Users who perform batch actions on Gerrit",
|
|
"group_id": 4,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
},
|
|
"Project Owners": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "global%3AProject-Owners",
|
|
"url": "#/admin/groups/uuid-global%3AProject-Owners",
|
|
"options": {
|
|
},
|
|
"description": "Any owner of the project",
|
|
"group_id": 5,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
},
|
|
"Registered Users": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "global%3ARegistered-Users",
|
|
"url": "#/admin/groups/uuid-global%3ARegistered-Users",
|
|
"options": {
|
|
},
|
|
"description": "Any signed-in user",
|
|
"group_id": 3,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
}
|
|
----
|
|
|
|
.Get all groups
|
|
****
|
|
get::/groups/
|
|
****
|
|
|
|
[[group-options]]
|
|
Group Options
|
|
^^^^^^^^^^^^^
|
|
Additional fields can be obtained by adding `o` parameters, each option
|
|
requires more lookups and slows down the query response time to the
|
|
client so they are generally disabled by default. Optional fields are:
|
|
|
|
[[includes]]
|
|
--
|
|
* `INCLUDES`: include list of directly included groups.
|
|
--
|
|
|
|
[[members]]
|
|
--
|
|
* `MEMBERS`: include list of direct group members.
|
|
--
|
|
|
|
Check if a group is owned by the calling user
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
By setting the option `owned` and specifying a group to inspect with
|
|
the option `q`, it is possible to find out, if this group is owned by
|
|
the calling user.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/?owned&q=MyProject-Committers HTTP/1.0
|
|
----
|
|
|
|
If the group is owned by the calling user, the returned map contains
|
|
this group. If the calling user doesn't own this group an empty map is
|
|
returned.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"MyProject-Committers": {
|
|
"kind": "gerritcodereview#group",
|
|
"id": "9999c971bb4ab872aab759d8c49833ee6b9ff320",
|
|
"url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
|
|
"options": {
|
|
"visible_to_all": true
|
|
},
|
|
"description":"contains all committers for MyProject",
|
|
"group_id": 551,
|
|
"owner": "MyProject-Owners",
|
|
"owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
|
|
}
|
|
}
|
|
----
|
|
|
|
[[get-group]]
|
|
Get Group
|
|
~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]'
|
|
|
|
Retrieves a group.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/6a1e70e1a88782771a91808c8af9bbb7a9871389 HTTP/1.0
|
|
----
|
|
|
|
As response a link:#group-info[GroupInfo] entity is returned that
|
|
describes the group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"name": "Administrators",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"description": "Gerrit Site Administrators",
|
|
"group_id": 1,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
----
|
|
|
|
[[create-group]]
|
|
Create Group
|
|
~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-name[\{group-name\}]'
|
|
|
|
Creates a new Gerrit internal group.
|
|
|
|
In the request body additional data for the group can be provided as
|
|
link:#group-input[GroupInput].
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/MyProject-Committers HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"description": "contains all committers for MyProject",
|
|
"visible_to_all": true,
|
|
"owner": "MyProject-Owners",
|
|
"owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
|
|
}
|
|
----
|
|
|
|
As response the link:#group-info[GroupInfo] entity is returned that
|
|
describes the created group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 201 Created
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "9999c971bb4ab872aab759d8c49833ee6b9ff320",
|
|
"name": "MyProject-Committers",
|
|
"url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
|
|
"options": {
|
|
"visible_to_all": true
|
|
},
|
|
"description":"contains all committers for MyProject",
|
|
"group_id": 551,
|
|
"owner": "MyProject-Owners",
|
|
"owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
|
|
}
|
|
----
|
|
|
|
If the group creation fails because the name is already in use the
|
|
response is "`409 Conflict`".
|
|
|
|
[[get-group-detail]]
|
|
Get Group Detail
|
|
~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/detail'
|
|
|
|
Retrieves a group with the direct link:#members[members] and the
|
|
directly link:#includes[included groups].
|
|
|
|
.Request
|
|
----
|
|
GET /groups/6a1e70e1a88782771a91808c8af9bbb7a9871389/detail HTTP/1.0
|
|
----
|
|
|
|
As response a link:#group-info[GroupInfo] entity is returned that
|
|
describes the group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"name": "Administrators",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"description": "Gerrit Site Administrators",
|
|
"group_id": 1,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"members": [
|
|
{
|
|
"_account_id": 1000097,
|
|
"name": "Jane Roe",
|
|
"email": "jane.roe@example.com"
|
|
},
|
|
{
|
|
"_account_id": 1000096,
|
|
"name": "John Doe",
|
|
"email": "john.doe@example.com"
|
|
}
|
|
],
|
|
"includes": []
|
|
}
|
|
----
|
|
|
|
[[get-group-name]]
|
|
Get Group Name
|
|
~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/name'
|
|
|
|
Retrieves the name of a group.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/name HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
"MyProject-Committers"
|
|
----
|
|
|
|
[[rename-group]]
|
|
Rename Group
|
|
~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-id[\{group-id\}]/name'
|
|
|
|
Renames a Gerrit internal group.
|
|
|
|
The new group name must be provided in the request body.
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/MyProject-Committers/name HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"name": "My-Project-Committers"
|
|
}
|
|
----
|
|
|
|
As response the new group name is returned.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
"My-Project-Committers"
|
|
----
|
|
|
|
If renaming the group fails because the new name is already in use the
|
|
response is "`409 Conflict`".
|
|
|
|
[[get-group-description]]
|
|
Get Group Description
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/description'
|
|
|
|
Retrieves the description of a group.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
"contains all committers for MyProject"
|
|
----
|
|
|
|
If the group does not have a description an empty string is returned.
|
|
|
|
[[set-group-description]]
|
|
Set Group Description
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-id[\{group-id\}]/description'
|
|
|
|
Sets the description of a Gerrit internal group.
|
|
|
|
The new group description must be provided in the request body.
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"description": "The committers of MyProject."
|
|
}
|
|
----
|
|
|
|
As response the new group description is returned.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
"The committers of MyProject."
|
|
----
|
|
|
|
If the description was deleted the response is "`204 No Content`".
|
|
|
|
[[delete-group-description]]
|
|
Delete Group Description
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'DELETE /groups/link:#group-id[\{group-id\}]/description'
|
|
|
|
Deletes the description of a Gerrit internal group.
|
|
|
|
.Request
|
|
----
|
|
DELETE /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 204 No Content
|
|
----
|
|
|
|
[[get-group-options]]
|
|
Get Group Options
|
|
~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/options'
|
|
|
|
Retrieves the options of a group.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/options HTTP/1.0
|
|
----
|
|
|
|
As response a link:#group-options-info[GroupOptionsInfo] entity is
|
|
returned that describes the options of the group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"visible_to_all": true
|
|
}
|
|
----
|
|
|
|
[[set-group-options]]
|
|
Set Group Options
|
|
~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-id[\{group-id\}]/options'
|
|
|
|
Sets the options of a Gerrit internal group.
|
|
|
|
The new group options must be provided in the request body as a
|
|
link:#group-options-input[GroupOptionsInput] entity.
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/options HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"visible_to_all": true
|
|
}
|
|
----
|
|
|
|
As response the new group options are returned as a
|
|
link:#group-options-info[GroupOptionsInfo] entity.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"visible_to_all": true
|
|
}
|
|
----
|
|
|
|
[[get-group-owner]]
|
|
Get Group Owner
|
|
~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/owner'
|
|
|
|
Retrieves the owner group of a Gerrit internal group.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/owner HTTP/1.0
|
|
----
|
|
|
|
As response a link:#group-info[GroupInfo] entity is returned that
|
|
describes the owner group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"name": "Administrators",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"description": "Gerrit Site Administrators",
|
|
"group_id": 1,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
----
|
|
|
|
[[set-group-owner]]
|
|
Set Group Owner
|
|
~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-id[\{group-id\}]/owner'
|
|
|
|
Sets the owner group of a Gerrit internal group.
|
|
|
|
The new owner group must be provided in the request body.
|
|
|
|
The new owner can be specified by name, by group UUID or by the legacy
|
|
numeric group ID.
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/9999c971bb4ab872aab759d8c49833ee6b9ff320/description HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"owner": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
----
|
|
|
|
As response a link:#group-info[GroupInfo] entity is returned that
|
|
describes the new owner group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"name": "Administrators",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"description": "Gerrit Site Administrators",
|
|
"group_id": 1,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
----
|
|
|
|
[[group-member-endpoints]]
|
|
Group Member Endpoints
|
|
----------------------
|
|
|
|
[[group-members]]
|
|
List Group Members
|
|
~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/members/'
|
|
|
|
Lists the direct members of a Gerrit internal group.
|
|
|
|
As result a list of detailed link:rest-api-accounts.html#account-info[
|
|
AccountInfo] entries is returned. The entries in the list are sorted by
|
|
full name, preferred email and id.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/ HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
[
|
|
{
|
|
"_account_id": 1000097,
|
|
"name": "Jane Roe",
|
|
"email": "jane.roe@example.com"
|
|
},
|
|
{
|
|
"_account_id": 1000096,
|
|
"name": "John Doe",
|
|
"email": "john.doe@example.com"
|
|
}
|
|
]
|
|
----
|
|
|
|
.Get all members of the 'Administrators' group (normally group id = 1)
|
|
****
|
|
get::/groups/1/members/
|
|
****
|
|
|
|
To resolve the included groups of a group recursively and to list all
|
|
members the parameter `recursive` can be set.
|
|
|
|
Members from included external groups and from included groups which
|
|
are not visible to the calling user are ignored.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/?recursive HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
[
|
|
{
|
|
"_account_id": 1000097,
|
|
"name": "Jane Roe",
|
|
"email": "jane.roe@example.com"
|
|
},
|
|
{
|
|
"_account_id": 1000096,
|
|
"name": "John Doe",
|
|
"email": "john.doe@example.com"
|
|
},
|
|
{
|
|
"_account_id": 1000098,
|
|
"name": "Richard Roe",
|
|
"email": "richard.roe@example.com"
|
|
}
|
|
]
|
|
----
|
|
|
|
[[get-group-member]]
|
|
Get Group Member
|
|
~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/members/link:rest-api-accounts.html#account-id[\{account-id\}]'
|
|
|
|
Retrieves a group member.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/1000096 HTTP/1.0
|
|
----
|
|
|
|
As response a detailed link:rest-api-accounts.html#account-info[
|
|
AccountInfo] entity is returned that describes the group member.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"_account_id": 1000096,
|
|
"name": "John Doe",
|
|
"email": "john.doe@example.com"
|
|
}
|
|
----
|
|
|
|
[[add-group-member]]
|
|
Add Group Member
|
|
~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-id[\{group-id\}]/members/link:rest-api-accounts.html#account-id[\{account-id\}]'
|
|
|
|
Adds a user as member to a Gerrit internal group.
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/MyProject-Committers/members/John%20Doe HTTP/1.0
|
|
----
|
|
|
|
As response a detailed link:rest-api-accounts.html#account-info[
|
|
AccountInfo] entity is returned that describes the group member.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 201 Created
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"_account_id": 1000037,
|
|
"name": "John Doe",
|
|
"email": "john.doe@example.com"
|
|
}
|
|
----
|
|
|
|
The request also succeeds if the user is already a member of this
|
|
group, but then the HTTP response code is `200 OK`.
|
|
|
|
Add Group Members
|
|
~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'POST /groups/link:#group-id[\{group-id\}]/members'
|
|
|
|
OR
|
|
|
|
[verse]
|
|
'POST /groups/link:#group-id[\{group-id\}]/members.add'
|
|
|
|
Adds one or several users to a Gerrit internal group.
|
|
|
|
The users to be added to the group must be provided in the request body
|
|
as a link:#members-input[MembersInput] entity.
|
|
|
|
.Request
|
|
----
|
|
POST /groups/MyProject-Committers/members.add HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"members": {
|
|
"jane.roe@example.com",
|
|
"john.doe@example.com"
|
|
}
|
|
}
|
|
----
|
|
|
|
As response a list of detailed link:rest-api-accounts.html#account-info[
|
|
AccountInfo] entities is returned that describes the group members that
|
|
were specified in the link:#members-input[MembersInput]. An
|
|
link:rest-api-accounts.html#account-info[AccountInfo] entity
|
|
is returned for each user specified in the input, independently of
|
|
whether the user was newly added to the group or whether the user was
|
|
already a member of the group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
[
|
|
{
|
|
"_account_id": 1000057,
|
|
"name": "Jane Roe",
|
|
"email": "jane.roe@example.com"
|
|
},
|
|
{
|
|
"_account_id": 1000037,
|
|
"name": "John Doe",
|
|
"email": "john.doe@example.com"
|
|
}
|
|
]
|
|
----
|
|
|
|
[[delete-group-member]]
|
|
Delete Group Member
|
|
~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'DELETE /groups/link:#group-id[\{group-id\}]/members/link:rest-api-accounts.html#account-id[\{account-id\}]'
|
|
|
|
Deletes a user from a Gerrit internal group.
|
|
|
|
.Request
|
|
----
|
|
DELETE /groups/MyProject-Committers/members/John%20Doe HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 204 No Content
|
|
----
|
|
|
|
[[delete-group-members]]
|
|
Delete Group Members
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'POST /groups/link:#group-id[\{group-id\}]/members.delete'
|
|
|
|
Delete one or several users from a Gerrit internal group.
|
|
|
|
The users to be deleted from the group must be provided in the request
|
|
body as a link:#members-input[MembersInput] entity.
|
|
|
|
.Request
|
|
----
|
|
POST /groups/MyProject-Committers/members.delete HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"members": {
|
|
"jane.roe@example.com",
|
|
"john.doe@example.com"
|
|
}
|
|
}
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 204 No Content
|
|
----
|
|
|
|
[[group-include-endpoints]]
|
|
Group Include Endpoints
|
|
-----------------------
|
|
|
|
[[included-groups]]
|
|
List Included Groups
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/groups/'
|
|
|
|
Lists the directly included groups of a group.
|
|
|
|
As result a list of link:#group-info[GroupInfo] entries is returned.
|
|
The entries in the list are sorted by group name and UUID.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/ HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
[
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
|
|
"name": "MyProject-Verifiers",
|
|
"url": "#/admin/groups/uuid-7ca042f4d5847936fcb90ca91057673157fd06fc",
|
|
"options": {
|
|
},
|
|
"group_id": 38,
|
|
"owner": "MyProject-Verifiers",
|
|
"owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
|
|
}
|
|
]
|
|
----
|
|
|
|
[[get-included-group]]
|
|
Get Included Group
|
|
~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'GET /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]'
|
|
|
|
Retrieves an included group.
|
|
|
|
.Request
|
|
----
|
|
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/7ca042f4d5847936fcb90ca91057673157fd06fc HTTP/1.0
|
|
----
|
|
|
|
As response a link:#group-info[GroupInfo] entity is returned that
|
|
describes the included group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "7ca042f4d5847936fcb90ca91057673157fd06fc",
|
|
"name": "MyProject-Verifiers",
|
|
"url": "#/admin/groups/uuid-7ca042f4d5847936fcb90ca91057673157fd06fc",
|
|
"options": {
|
|
},
|
|
"group_id": 38,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
----
|
|
|
|
[[include-group]]
|
|
Include Group
|
|
~~~~~~~~~~~~~
|
|
[verse]
|
|
'PUT /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]'
|
|
|
|
Includes a group into a Gerrit internal group.
|
|
|
|
.Request
|
|
----
|
|
PUT /groups/MyProject-Committers/groups/MyGroup HTTP/1.0
|
|
----
|
|
|
|
As response a link:#group-info[GroupInfo] entity is returned that
|
|
describes the included group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 201 Created
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"name": "MyGroup",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"group_id": 8,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
}
|
|
----
|
|
|
|
The request also succeeds if the group is already included in this
|
|
group, but then the HTTP response code is `200 OK`.
|
|
|
|
[[include-groups]]
|
|
Include Groups
|
|
~~~~~~~~~~~~~~
|
|
[verse]
|
|
'POST /groups/link:#group-id[\{group-id\}]/groups'
|
|
|
|
OR
|
|
|
|
[verse]
|
|
'POST /groups/link:#group-id[\{group-id\}]/groups.add'
|
|
|
|
Includes one or several groups into a Gerrit internal group.
|
|
|
|
The groups to be included into the group must be provided in the
|
|
request body as a link:#groups-input[GroupsInput] entity.
|
|
|
|
.Request
|
|
----
|
|
POST /groups/MyProject-Committers/groups.add HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"groups": {
|
|
"MyGroup",
|
|
"MyOtherGroup"
|
|
}
|
|
}
|
|
----
|
|
|
|
As response a list of link:#group-info[GroupInfo] entities is
|
|
returned that describes the groups that were specified in the
|
|
link:#groups-input[GroupsInput]. A link:#group-info[GroupInfo] entity
|
|
is returned for each group specified in the input, independently of
|
|
whether the group was newly included into the group or whether the
|
|
group was already included in the group.
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 200 OK
|
|
Content-Disposition: attachment
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
)]}'
|
|
[
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"name": "MyGroup",
|
|
"url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389",
|
|
"options": {
|
|
},
|
|
"group_id": 8,
|
|
"owner": "Administrators",
|
|
"owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
|
|
},
|
|
{
|
|
"kind": "gerritcodereview#group",
|
|
"id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
|
|
"name": "MyOtherGroup",
|
|
"url": "#/admin/groups/uuid-5057f3cbd3519d6ab69364429a89ffdffba50f73",
|
|
"options": {
|
|
},
|
|
"group_id": 10,
|
|
"owner": "MyOtherGroup",
|
|
"owner_id": "5057f3cbd3519d6ab69364429a89ffdffba50f73"
|
|
}
|
|
]
|
|
----
|
|
|
|
[[delete-included-group]]
|
|
Delete Included Group
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'DELETE /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]'
|
|
|
|
Deletes an included group from a Gerrit internal group.
|
|
|
|
.Request
|
|
----
|
|
DELETE /groups/MyProject-Committers/groups/MyGroup HTTP/1.0
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 204 No Content
|
|
----
|
|
|
|
[[delete-included-groups]]
|
|
Delete Included Groups
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
[verse]
|
|
'POST /groups/link:#group-id[\{group-id\}]/groups.delete'
|
|
|
|
Delete one or several included groups from a Gerrit internal group.
|
|
|
|
The groups to be deleted from the group must be provided in the request
|
|
body as a link:#groups-input[GroupsInput] entity.
|
|
|
|
.Request
|
|
----
|
|
POST /groups/MyProject-Committers/groups.delete HTTP/1.0
|
|
Content-Type: application/json;charset=UTF-8
|
|
|
|
{
|
|
"members": {
|
|
"MyGroup",
|
|
"MyOtherGroup"
|
|
}
|
|
}
|
|
----
|
|
|
|
.Response
|
|
----
|
|
HTTP/1.1 204 No Content
|
|
----
|
|
|
|
|
|
[[ids]]
|
|
IDs
|
|
---
|
|
|
|
[[account-id]]
|
|
link:rest-api-accounts.html#account-id[\{account-id\}]
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
--
|
|
--
|
|
|
|
[[group-id]]
|
|
\{group-id\}
|
|
~~~~~~~~~~~~
|
|
Identifier for a group.
|
|
|
|
This can be:
|
|
|
|
* the UUID of the group
|
|
* the legacy numeric ID of the group
|
|
* the name of the group if it is unique
|
|
|
|
[[group-name]]
|
|
\{group-name\}
|
|
~~~~~~~~~~~~~~
|
|
Group name that uniquely identifies one group.
|
|
|
|
|
|
[[json-entities]]
|
|
JSON Entities
|
|
-------------
|
|
|
|
[[group-info]]
|
|
GroupInfo
|
|
~~~~~~~~~
|
|
The `GroupInfo` entity contains information about a group. This can be
|
|
a Gerrit internal group, or an external group that is known to Gerrit.
|
|
|
|
[options="header",width="50%",cols="1,^1,5"]
|
|
|===========================
|
|
|Field Name ||Description
|
|
|`kind` ||`gerritcodereview#group`
|
|
|`id` ||The URL encoded UUID of the group.
|
|
|`name` |
|
|
not set if returned in a map where the group name is used as map key|
|
|
The name of the group.
|
|
|`url` |optional|
|
|
URL to information about the group. Typically a URL to a web page that
|
|
permits users to apply to join the group, or manage their membership.
|
|
|`options` ||link:#group-options-info[Options of the group]
|
|
|`description` |only for internal groups|The description of the group.
|
|
|`group_id` |only for internal groups|The numeric ID of the group.
|
|
|`owner` |only for internal groups|The name of the owner group.
|
|
|`owner_id` |only for internal groups|The URL encoded UUID of the owner group.
|
|
|`members` |optional, only for internal groups|
|
|
A list of link:rest-api-accounts.html#account-info[AccountInfo]
|
|
entities describing the direct members. +
|
|
Only set if link:#members[members] are requested.
|
|
|`includes` |optional, only for internal groups|
|
|
A list of link:#group-info[GroupInfo] entities describing the directly
|
|
included groups. +
|
|
Only set if link:#includes[included groups] are requested.
|
|
|===========================
|
|
|
|
The type of a group can be deduced from the group's UUID:
|
|
[width="50%"]
|
|
|============
|
|
|UUID matches "^[0-9a-f]\{40\}$"|Gerrit internal group
|
|
|UUID starts with "global:"|Gerrit system group
|
|
|UUID starts with "ldap:"|LDAP group
|
|
|UUID starts with "<prefix>:"|other external group
|
|
|============
|
|
|
|
[[group-input]]
|
|
GroupInput
|
|
~~~~~~~~~~
|
|
The 'GroupInput' entity contains information for the creation of
|
|
a new internal group.
|
|
|
|
[options="header",width="50%",cols="1,^1,5"]
|
|
|===========================
|
|
|Field Name ||Description
|
|
|`name` |optional|The name of the group (not encoded). +
|
|
If set, must match the group name in the URL.
|
|
|`description` |optional|The description of the group.
|
|
|`visible_to_all`|optional|
|
|
Whether the group is visible to all registered users. +
|
|
`false` if not set.
|
|
|`owner_id`|optional|The URL encoded ID of the owner group. +
|
|
This can be a group UUID, a legacy numeric group ID or a unique group
|
|
name. +
|
|
If not set, the new group will be self-owned.
|
|
|===========================
|
|
|
|
[[groups-input]]
|
|
GroupsInput
|
|
~~~~~~~~~~~
|
|
The `GroupsInput` entity contains information about groups that should
|
|
be included into a group or that should be deleted from a group.
|
|
|
|
[options="header",width="50%",cols="1,^1,5"]
|
|
|==========================
|
|
|Field Name ||Description
|
|
|`_one_group` |optional|
|
|
The link:#group-id[id] of one group that should be included or deleted.
|
|
|`groups` |optional|
|
|
A list of link:#group-id[group ids] that identify the groups that
|
|
should be included or deleted.
|
|
|==========================
|
|
|
|
[[group-options-info]]
|
|
GroupOptionsInfo
|
|
~~~~~~~~~~~~~~~~
|
|
Options of the group.
|
|
|
|
[options="header",width="50%",cols="1,^1,5"]
|
|
|=============================
|
|
|Field Name ||Description
|
|
|`visible_to_all`|not set if `false`|
|
|
Whether the group is visible to all registered users.
|
|
|=============================
|
|
|
|
[[group-options-input]]
|
|
GroupOptionsInput
|
|
~~~~~~~~~~~~~~~~~
|
|
New options for a group.
|
|
|
|
[options="header",width="50%",cols="1,^1,5"]
|
|
|=============================
|
|
|Field Name ||Description
|
|
|`visible_to_all`|not set if `false`|
|
|
Whether the group is visible to all registered users.
|
|
|=============================
|
|
|
|
[[members-input]]
|
|
MembersInput
|
|
~~~~~~~~~~~
|
|
The `MembersInput` entity contains information about accounts that should
|
|
be added as members to a group or that should be deleted from the group.
|
|
|
|
[options="header",width="50%",cols="1,^1,5"]
|
|
|==========================
|
|
|Field Name ||Description
|
|
|`_one_member`|optional|
|
|
The link:#account-id[id] of one account that should be added or
|
|
deleted.
|
|
|`members` |optional|
|
|
A list of link:#account-id[account ids] that identify the accounts that
|
|
should be added or deleted.
|
|
|==========================
|
|
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|