| 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]. |
| |
| Endpoints |
| --------- |
| |
| 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. |
| |
| ---- |
| GET /groups/ HTTP/1.0 |
| |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "Administrators": { |
| "kind": "gerritcodereview#group", |
| "id": "6a1e70e1a88782771a91808c8af9bbb7a9871389", |
| "description": "Gerrit Site Administrators", |
| "group_id": 1, |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| }, |
| "Anonymous Users": { |
| "kind": "gerritcodereview#group", |
| "id": "global%3AAnonymous-Users", |
| "description": "Any user, signed-in or not", |
| "group_id": 2, |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| }, |
| "MyProject_Committers": { |
| "kind": "gerritcodereview#group", |
| "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "visible_to_all": true, |
| "group_id": 6, |
| "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7" |
| }, |
| "Non-Interactive Users": { |
| "kind": "gerritcodereview#group", |
| "id": "5057f3cbd3519d6ab69364429a89ffdffba50f73", |
| "description": "Users who perform batch actions on Gerrit", |
| "group_id": 4, |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| }, |
| "Project Owners": { |
| "kind": "gerritcodereview#group", |
| "id": "global%3AProject-Owners", |
| "description": "Any owner of the project", |
| "group_id": 5, |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| }, |
| "Registered Users": { |
| "kind": "gerritcodereview#group", |
| "id": "global%3ARegistered-Users", |
| "description": "Any signed-in user", |
| "group_id": 3, |
| "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389" |
| } |
| } |
| ---- |
| |
| .Get all groups |
| **** |
| get::/groups/ |
| **** |
| |
| [[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. |
| |
| ---- |
| GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/ HTTP/1.0 |
| |
| 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. |
| |
| ---- |
| GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/members/?recursive HTTP/1.0 |
| |
| 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" |
| } |
| ] |
| ---- |
| |
| [[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. |
| |
| ---- |
| GET /groups/834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7/groups/ HTTP/1.0 |
| |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "kind": "gerritcodereview#group", |
| "id": "7ca042f4d5847936fcb90ca91057673157fd06fc", |
| "name": "MyProject-Verifiers", |
| "group_id": 38, |
| "owner_id": "7ca042f4d5847936fcb90ca91057673157fd06fc" |
| } |
| ] |
| ---- |
| |
| [[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]. |
| |
| ---- |
| 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" |
| } |
| ---- |
| |
| |
| [[ids]] |
| IDs |
| --- |
| |
| \{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. |
| |=========================== |
| |
| [[group-options-info]] |
| GroupOptionsInfo |
| ~~~~~~~~~~~~~~~~ |
| Options of the group. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |============================= |
| |Field Name ||Description |
| |`kind` ||`gerritcodereview#groupoptions` |
| |`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. |
| |=============================== |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
