opendev/gerrit
Code Issues Proposed changes
gerrit/Documentation/rest-api-groups.txt
Edwin Kempin c977090b26 Accept group UUID and group ID as input for setting group owner via REST 
At the moment the new owner can only be specified by name.

Change-Id: I3235ee9f19665ad73f5c163800daf6edfcecfad4
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
2013-02-15 15:44:13 +01:00

1100 lines
28 KiB
Plaintext
Raw Blame History

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]]
GET /groups/ (List 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_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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
},
"MyProject_Committers": {
"kind": "gerritcodereview#group",
"id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
"url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
"options": {
"visible_to_all": true,
},
"group_id": 6,
"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_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_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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
}
}
----
.Get all groups
****
get::/groups/
****
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",
"name": "MyProject-Committers",
"url": "#/admin/groups/uuid-9999c971bb4ab872aab759d8c49833ee6b9ff320",
"options": {
"visible_to_all": true
},
"description":"contains all committers for MyProject",
"group_id": 551,
"owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
}
}
----
[[get-group]]
GET /groups/\{group-id\} (Get Group)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
}
----
[[create-group]]
PUT /groups/\{group-name\} (Create Group)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_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_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
}
----
[[get-group-name]]
GET /groups/\{group-id\}/name (Get Group 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]]
PUT /groups/\{group-id\}/name (Rename Group)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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"
----
[[get-group-description]]
GET /groups/\{group-id\}/description (Get Group 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"
----
[[set-group-description]]
PUT /groups/\{group-id\}/description (Set Group 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."
----
[[delete-group-description]]
DELETE /groups/\{group-id\}/description (Delete Group 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 /groups/\{group-id\}/options (Get Group 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]]
PUT /groups/\{group-id\}/options (Set Group 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 /groups/\{group-id\}/owner (Get Group 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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
}
----
[[set-group-owner]]
PUT /groups/\{group-id\}/owner (Set Group 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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
}
----
[[group-member-endpoints]]
Group Member Endpoints
----------------------
[[group-members]]
GET /groups/\{group-id\}/members/ (List Group Members)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lists the direct members of a group.
As result a list of link:#member-info[MemberInfo] 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
)]}'
[
{
"kind": "gerritcodereview#member",
"full_name": "Jane Roe",
"id": "1000097",
"account_id": 1000097,
"preferred_email": "jane.roe@example.com",
"user_name": "jane"
},
{
"kind": "gerritcodereview#member",
"full_name": "John Doe",
"id": "1000096",
"account_id": 1000096,
"preferred_email": "john.doe@example.com",
"user_name": "doe"
}
]
----
.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.
.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
)]}'
[
{
"kind": "gerritcodereview#member",
"full_name": "Jane Roe",
"id": "1000097",
"account_id": 1000097,
"preferred_email": "jane.roe@example.com",
"user_name": "jane"
},
{
"kind": "gerritcodereview#member",
"full_name": "John Doe",
"id": "1000096",
"account_id": 1000096,
"preferred_email": "john.doe@example.com",
"user_name": "doe"
},
{
"kind": "gerritcodereview#member",
"full_name": "Richard Roe",
"id": "1000098",
"account_id": 1000098,
"preferred_email": "richard.roe@example.com",
"user_name": "richard"
}
]
----
[[get-group-member]]
GET /groups/\{group-id\}/members/\{account-id\} (Get Group Member)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a group member.
.Request
----
GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/1000096 HTTP/1.0
----
As response a link:#member-info[MemberInfo] entity is returned that
describes the group member.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#member",
"full_name": "John Doe",
"id": "1000096",
"account_id": 1000096,
"preferred_email": "john.doe@example.com",
"user_name": "doe"
}
----
[[add-group-member]]
PUT /groups/\{group-id\}/members/\{account-id\} (Add Group Member)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adds a user as member to a Gerrit internal group.
.Request
----
PUT /groups/MyProject-Committers/members/John%20Doe HTTP/1.0
----
As response a link:#member-info[MemberInfo] entity is returned that
describes the group member.
.Response
----
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#member",
"full_name": "John Doe",
"id": "1000037",
"account_id": 1000037,
"preferred_email": "john.doe@example.com",
"user_name": "jdoe"
}
----
The request also succeeds if the user is already a member of this
group, but then the HTTP response code is `200 OK`.
POST /groups/\{group-id\}/members (Add Group Members)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Same as link:#add-group-members[POST /groups/\{group-id\}/members.add].
[[add-group-members]]
POST /groups/\{group-id\}/members.add (Add Group Members)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:#member-input[MemberInput] 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 link:#member-info[MemberInfo] entities is
returned that describes the group members that were specified in the
link:#member-input[MemberInput]. A link:#member-info[MemberInfo] 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
)]}'
[
{
"kind": "gerritcodereview#member",
"full_name": "Jane Roe",
"id": "1000057",
"account_id": 1000057,
"preferred_email": "jane.roe@example.com",
"user_name": "jroe"
},
{
"kind": "gerritcodereview#member",
"full_name": "John Doe",
"id": "1000037",
"account_id": 1000037,
"preferred_email": "john.doe@example.com",
"user_name": "jdoe"
}
]
----
[[delete-group-member]]
DELETE /groups/\{group-id\}/members/\{account-id\} (Delete Group Member)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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]]
POST /groups/\{group-id\}/members.delete (Delete Group Members)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:#member-input[MemberInput] 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]]
GET /groups/\{group-id\}/groups/ (List Included 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_id": "7ca042f4d5847936fcb90ca91057673157fd06fc"
}
]
----
[[get-included-group]]
GET /groups/\{group-id\}/groups/\{group-id\} (Get Included Group)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
}
----
[[include-group]]
PUT /groups/\{group-id\}/groups/\{group-id\} (Include Group)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
}
----
The request also succeeds if the group is already included in this
group, but then the HTTP response code is `200 OK`.
POST /groups/\{group-id\}/groups (Include Groups)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Same as link:#include-groups[POST /groups/\{group-id\}/groups.add].
[[include-groups]]
POST /groups/\{group-id\}/groups.add (Include Groups)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
},
{
"kind": "gerritcodereview#group",
"id": "5057f3cbd3519d6ab69364429a89ffdffba50f73",
"name": "MyOtherGroup",
"url": "#/admin/groups/uuid-5057f3cbd3519d6ab69364429a89ffdffba50f73",
"options": {
},
"group_id": 10,
"owner_id": "5057f3cbd3519d6ab69364429a89ffdffba50f73"
}
]
----
[[delete-included-group]]
DELETE /groups/\{group-id\}/groups/\{group-id\} (Delete Included Group)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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]]
POST /groups/\{group-id\}/groups.delete (Delete Included Groups)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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]]
\{account-id\}
~~~~~~~~~~~~~~
Identifier that uniquely identifies one account.
This can be:
* a string of the format "Full Name <email@example.com>"
* just the email address ("email@example")
* a full name if it is unique ("Full Name")
* an account ID ("18419")
* a user name ("username")
[[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 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` ||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_id` |only for internal groups|The URL encoded UUID of the owner group.
|===========================
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.
|=============================
[[member-info]]
MemberInfo
~~~~~~~~~~
The `MemberInfo` entity contains information about an account that is
member of a group.
[options="header",width="50%",cols="1,^1,5"]
|===============================
|Field Name ||Description
|`kind` ||`gerritcodereview#member`
|`id` ||The URL encoded ID of the account.
|`account_id` ||The numeric ID of the account.
|`full_name` |optional|
The full name of the user ("Given-name Surname" style).
|`preferred_email` |optional|
The email address the user prefers to be contacted through.
|`user_name` ||The user name.
|===============================
[[member-input]]
MemberInput
~~~~~~~~~~~
The `MemberInput` 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]
View Git Blame Copy Permalink