| = 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 |
| -- |
| '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": { |
| "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389", |
| "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389", |
| "options": { |
| }, |
| "description": "Gerrit Site Administrators", |
| "group_id": 1, |
| "owner": "Administrators", |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| }, |
| "Anonymous Users": { |
| "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": { |
| "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "options": { |
| "visible_to_all": true, |
| }, |
| "group_id": 6, |
| "owner": "MyProject_Committers", |
| "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7" |
| }, |
| "Non-Interactive Users": { |
| "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": { |
| "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": { |
| "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": { |
| "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" |
| } |
| } |
| ---- |
| |
| [[group-limit]] |
| ==== Group Limit |
| The `/groups/` URL also accepts a limit integer in the `n` parameter. |
| This limits the results to show `n` groups. |
| |
| Query the first 25 groups in group list. |
| ---- |
| GET /groups/?n=25 HTTP/1.0 |
| ---- |
| |
| The `/groups/` URL also accepts a start integer in the `S` parameter. |
| The results will skip `S` groups from group list. |
| |
| Query 25 groups starting from index 50. |
| ---- |
| GET /groups/?n=25&S=50 HTTP/1.0 |
| ---- |
| |
| [[get-group]] |
| === Get Group |
| -- |
| '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 |
| |
| )]}' |
| { |
| "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 |
| -- |
| '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 |
| |
| )]}' |
| { |
| "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 |
| -- |
| '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 |
| |
| )]}' |
| { |
| "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", |
| "username": "jane" |
| }, |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com" |
| "username": "john" |
| } |
| ], |
| "includes": [] |
| } |
| ---- |
| |
| [[get-group-name]] |
| === Get Group Name |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| |
| )]}' |
| { |
| "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 |
| -- |
| '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 |
| |
| )]}' |
| { |
| "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 |
| -- |
| '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", |
| "username": "jane" |
| }, |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "john" |
| } |
| ] |
| ---- |
| |
| .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", |
| "username": "jane" |
| }, |
| { |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "john" |
| }, |
| { |
| "_account_id": 1000098, |
| "name": "Richard Roe", |
| "email": "richard.roe@example.com", |
| "username": "rroe" |
| } |
| ] |
| ---- |
| |
| [[get-group-member]] |
| === Get Group Member |
| -- |
| '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", |
| "username": "john" |
| } |
| ---- |
| |
| [[add-group-member]] |
| === Add Group Member |
| -- |
| '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", |
| "username": "john" |
| } |
| ---- |
| |
| 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 |
| -- |
| 'POST /groups/link:#group-id[\{group-id\}]/members' |
| -- |
| |
| OR |
| |
| -- |
| '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", |
| "username": "jane" |
| }, |
| { |
| "_account_id": 1000037, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "john" |
| } |
| ] |
| ---- |
| |
| [[delete-group-member]] |
| === Delete Group Member |
| -- |
| '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 |
| -- |
| '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 |
| -- |
| '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 |
| |
| )]}' |
| [ |
| { |
| "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 |
| -- |
| '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 |
| |
| )]}' |
| { |
| "id": "7ca042f4d5847936fcb90ca91057673157fd06fc", |
| "name": "MyProject-Verifiers", |
| "url": "#/admin/groups/uuid-7ca042f4d5847936fcb90ca91057673157fd06fc", |
| "options": { |
| }, |
| "group_id": 38, |
| "owner": "Administrators", |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| } |
| ---- |
| |
| [[include-group]] |
| === Include Group |
| -- |
| 'PUT /groups/link:#group-id[\{group-id\}]/groups/link:#group-id[\{group-id\}]' |
| -- |
| |
| Includes an internal or external group into a Gerrit internal group. |
| External groups must be specified using the UUID. |
| |
| .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 |
| |
| )]}' |
| { |
| "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 |
| -- |
| 'POST /groups/link:#group-id[\{group-id\}]/groups' |
| -- |
| |
| OR |
| |
| -- |
| '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 |
| |
| )]}' |
| [ |
| { |
| "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389", |
| "name": "MyGroup", |
| "url": "#/admin/groups/uuid-6a1e70e1a88782771a91808c8af9bbb7a9871389", |
| "options": { |
| }, |
| "group_id": 8, |
| "owner": "Administrators", |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| }, |
| { |
| "id": "5057f3cbd3519d6ab69364429a89ffdffba50f73", |
| "name": "MyOtherGroup", |
| "url": "#/admin/groups/uuid-5057f3cbd3519d6ab69364429a89ffdffba50f73", |
| "options": { |
| }, |
| "group_id": 10, |
| "owner": "MyOtherGroup", |
| "owner_id": "5057f3cbd3519d6ab69364429a89ffdffba50f73" |
| } |
| ] |
| ---- |
| |
| [[delete-included-group]] |
| === Delete Included Group |
| -- |
| '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 |
| -- |
| '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 |
| |
| { |
| "groups": [ |
| "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 |
| |`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] |
| |
| SEARCHBOX |
| --------- |
