| Gerrit Code Review - /accounts/ REST API |
| ======================================== |
| |
| This page describes the account related REST endpoints. |
| Please also take note of the general information on the |
| link:rest-api.html[REST API]. |
| |
| Endpoints |
| --------- |
| |
| [[get-account]] |
| Get Account |
| ~~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]' |
| |
| Returns an account as an link:#account-info[AccountInfo] entity. |
| |
| .Request |
| ---- |
| GET /accounts/self HTTP/1.0 |
| ---- |
| |
| .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" |
| } |
| ---- |
| |
| [[list-account-capabilities]] |
| List Account Capabilities |
| ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]/capabilities' |
| |
| Returns the global capabilities that are enabled for the specified |
| user. |
| |
| If the global capabilities for the calling user should be listed, |
| `self` can be used as account-id. This can be used by UI tools to |
| discover if administrative features are available to the caller, so |
| they can hide (or show) relevant UI actions. |
| |
| .Request |
| ---- |
| GET /accounts/self/capabilities HTTP/1.0 |
| ---- |
| |
| As response the global capabilities of the user are returned as a |
| link:#capability-info[CapabilityInfo] entity. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "queryLimit": { |
| "min": 0, |
| "max": 500 |
| }, |
| "emailReviewers": true |
| } |
| ---- |
| |
| Administrator that has authenticated with digest authentication: |
| |
| .Request |
| ---- |
| GET /a/accounts/self/capabilities HTTP/1.0 |
| Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="... |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "administrateServer": true, |
| "queryLimit": { |
| "min": 0, |
| "max": 500 |
| }, |
| "createAccount": true, |
| "createGroup": true, |
| "createProject": true, |
| "emailReviewers": true, |
| "killTask": true, |
| "viewCaches": true, |
| "flushCaches": true, |
| "viewConnections": true, |
| "viewQueue": true, |
| "runGC": true, |
| "startReplication": true |
| } |
| ---- |
| |
| .Get your own capabilities |
| **** |
| get::/accounts/self/capabilities |
| **** |
| |
| To filter the set of global capabilities the `q` parameter can be used. |
| Filtering may decrease the response time by avoiding looking at every |
| possible alternative for the caller. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/capabilities?q=createAccount&q=createGroup HTTP/1.0 |
| Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="... |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "createAccount": true, |
| "createGroup": true |
| } |
| ---- |
| |
| .Check if you can create groups |
| **** |
| get::/accounts/self/capabilities?q=createGroup |
| **** |
| |
| [[check-account-capability]] |
| Check Account Capability |
| ~~~~~~~~~~~~~~~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]/capabilities/link:#capability-id[\{capability-id\}]' |
| |
| Checks if a user has a certain global capability. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/capabilities/createGroup HTTP/1.0 |
| ---- |
| |
| If the user has the global capability the string `ok` is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| |
| ok |
| ---- |
| |
| If the user doesn't have the global capability the response is |
| `404 Not Found`. |
| |
| .Check if you can create groups |
| **** |
| get::/accounts/self/capabilities/createGroup |
| **** |
| |
| [[list-groups]] |
| List Groups |
| ~~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]/groups/' |
| |
| Lists all groups that contain the specified user as a member. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/groups/ HTTP/1.0 |
| ---- |
| |
| As result a list of link:rest-api-groups.html#group-info[GroupInfo] |
| entries is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "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" |
| }, |
| { |
| "kind": "gerritcodereview#group", |
| "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "options": { |
| "visible_to_all": true, |
| }, |
| "group_id": 6, |
| "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7" |
| }, |
| { |
| "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" |
| } |
| ] |
| ---- |
| |
| .List all groups that contain you as a member |
| **** |
| get::/accounts/self/groups/ |
| **** |
| |
| [[get-avatar]] |
| Get Avatar |
| ~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]/avatar' |
| |
| Retrieves the avatar image of the user. |
| |
| With the `size` option (alias `s`) you can specify the preferred size |
| in pixels (height and width). |
| |
| .Request |
| ---- |
| GET /a/accounts/john.doe@example.com/avatar?s=20 HTTP/1.0 |
| ---- |
| |
| The response redirects to the URL of the avatar image. |
| |
| .Response |
| ---- |
| HTTP/1.1 302 Found |
| Location: https://profiles/avatar/john_doe.jpeg?s=20x20 |
| ---- |
| |
| [[get-avatar-change-url]] |
| Get Avatar Change URL |
| ~~~~~~~~~~~~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]/avatar.change.url' |
| |
| Retrieves the URL where the user can change the avatar image. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/avatar.change.url HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: text/plain;charset=UTF-8 |
| |
| https://profiles/pictures/john.doe |
| ---- |
| |
| [[get-diff-preferences]] |
| Get Diff Preferences |
| ~~~~~~~~~~~~~~~~~~~~ |
| [verse] |
| 'GET /accounts/link:#account-id[\{account-id\}]/preferences.diff' |
| |
| Retrieves the diff preferences of a user. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/preferences.diff HTTP/1.0 |
| ---- |
| |
| As result the diff preferences of the user are returned as a |
| link:#diff-preferences-info[DiffPreferencesInfo] entity. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "context": 10, |
| "ignore_whitespace": "IGNORE_ALL_SPACE", |
| "intraline_difference": true, |
| "line_length": 100, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "tab_size": 8 |
| } |
| ---- |
| |
| [[set-diff-preferences]] |
| Set Diff Preferences |
| ~~~~~~~~~~~~~~~~~~~~ |
| [verse] |
| 'PUT /accounts/link:#account-id[\{account-id\}]/preferences.diff' |
| |
| Sets the diff preferences of a user. |
| |
| The new diff preferences must be provided in the request body as a |
| link:#diff-preferences-input[DiffPreferencesInput] entity. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/preferences.diff HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "context": 10, |
| "ignore_whitespace": "IGNORE_ALL_SPACE", |
| "intraline_difference": true, |
| "line_length": 100, |
| "show_line_endings": true, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "tab_size": 8 |
| } |
| ---- |
| |
| As result the new diff preferences of the user are returned as a |
| link:#diff-preferences-info[DiffPreferencesInfo] entity. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "context": 10, |
| "ignore_whitespace": "IGNORE_ALL_SPACE", |
| "intraline_difference": true, |
| "line_length": 100, |
| "show_line_endings": true, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "tab_size": 8 |
| } |
| ---- |
| |
| |
| [[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") |
| * `self` for the calling user |
| |
| [[capability-id]] |
| \{capability-id\} |
| ~~~~~~~~~~~~~~~~~ |
| Identifier of a global capability. Valid values are all field names of |
| the link:#capability-info[CapabilityInfo] entity. |
| |
| |
| [[json-entities]] |
| JSON Entities |
| ------------- |
| |
| [[account-info]] |
| AccountInfo |
| ~~~~~~~~~~~ |
| The `AccountInfo` entity contains information about an account. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`_account_id` ||The numeric ID of the account. |
| |`name` |optional|The full name of the user. + |
| Only set if detailed account information is requested. |
| |`email` |optional| |
| The email address the user prefers to be contacted through. + |
| Only set if detailed account information is requested. |
| |=========================== |
| |
| [[capability-info]] |
| CapabilityInfo |
| ~~~~~~~~~~~~~~ |
| The `CapabilityInfo` entity contains information about the global |
| capabilities of a user. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |================================= |
| |Field Name ||Description |
| |`administrateServer`|not set if `false`|Whether the user has the |
| link:access-control.html#capability_administrateServer[Administrate |
| Server] capability. |
| |`queryLimit`||The link:access-control.html#capability_queryLimit[Query |
| Limit] of the user as link:#query-limit-info[QueryLimitInfo]. |
| |`createAccount` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_createAccount[Create Account] |
| capability. |
| |`createGroup` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_createGroup[Create Group] |
| capability. |
| |`createProject` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_createProject[Create Project] |
| capability. |
| |`emailReviewers` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_emailReviewers[Email Reviewers] |
| capability. |
| |`killTask` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_kill[Kill Task] capability. |
| |`viewCaches` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewCaches[View Caches] capability. |
| |`flushCaches` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_flushCaches[Flush Caches] |
| capability. |
| |`viewConnections` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewConnections[View Connections] |
| capability. |
| |`viewQueue` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewQueue[View Queue] capability. |
| |`runGC` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_runGC[Run Garbage Collection] |
| capability. |
| |`startReplication` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_startReplication[Start Replication] |
| capability. |
| |================================= |
| |
| [[diff-preferences-info]] |
| DiffPreferencesInfo |
| ~~~~~~~~~~~~~~~~~~~ |
| The `DiffPreferencesInfo` entity contains information about the diff |
| preferences of a user. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |===================================== |
| |Field Name ||Description |
| |`context` || |
| The number of lines of context when viewing a patch. |
| |`expand_all_comments` |not set if `false`| |
| Whether all inline comments should be automatically expanded. |
| |`ignore_whitespace` || |
| Whether whitespace changes should be ignored and if yes, which |
| whitespace changes should be ignored. + |
| Allowed values are `IGNORE_NONE`, `IGNORE_SPACE_AT_EOL`, |
| `IGNORE_SPACE_CHANGE`, `IGNORE_ALL_SPACE`. |
| |`intraline_difference` |not set if `false`| |
| Whether intraline differences should be highlighted. |
| |`line_length` || |
| Number of characters that should be displayed in one line. |
| |`manual_review` |not set if `false`| |
| Whether the 'Reviewed' flag should not be set automatically on a patch |
| when it is viewed. |
| |`retain_header` |not set if `false`| |
| Whether the header that is displayed above the patch (that either shows |
| the commit message, the diff preferences, the patch sets or the files) |
| should be retained on file switch. |
| |`show_line_endings` |not set if `false`| |
| Whether Windows EOL/Cr-Lf should be displayed as '\r' in a dotted-line |
| box. |
| |`show_tabs` |not set if `false`| |
| Whether tabs should be shown. |
| |`show_whitespace_errors`|not set if `false`| |
| Whether whitespace errors should be shown. |
| |`skip_deleted` |not set if `false`| |
| Whether deleted files should be skipped on file switch. |
| |`skip_uncommented` |not set if `false`| |
| Whether uncommented files should be skipped on file switch. |
| |`syntax_highlighting` |not set if `false`| |
| Whether syntax highlighting should be enabled. |
| |`tab_size` || |
| Number of spaces that should be used to display one tab. |
| |===================================== |
| |
| [[diff-preferences-input]] |
| DiffPreferencesInput |
| ~~~~~~~~~~~~~~~~~~~~ |
| The `DiffPreferencesInput` entity contains information for setting the |
| diff preferences of a user. Fields which are not set will not be |
| updated. |
| |
| [options="header",width="50%",cols="1,^1,5"] |
| |===================================== |
| |Field Name ||Description |
| |`context` |optional| |
| The number of lines of context when viewing a patch. |
| |`expand_all_comments` |optional| |
| Whether all inline comments should be automatically expanded. |
| |`ignore_whitespace` |optional| |
| Whether whitespace changes should be ignored and if yes, which |
| whitespace changes should be ignored. + |
| Allowed values are `IGNORE_NONE`, `IGNORE_SPACE_AT_EOL`, |
| `IGNORE_SPACE_CHANGE`, `IGNORE_ALL_SPACE`. |
| |`intraline_difference` |optional| |
| Whether intraline differences should be highlighted. |
| |`line_length` |optional| |
| Number of characters that should be displayed in one line. |
| |`manual_review` |optional| |
| Whether the 'Reviewed' flag should not be set automatically on a patch |
| when it is viewed. |
| |`retain_header` |optional| |
| Whether the header that is displayed above the patch (that either shows |
| the commit message, the diff preferences, the patch sets or the files) |
| should be retained on file switch. |
| |`show_line_endings` |optional| |
| Whether Windows EOL/Cr-Lf should be displayed as '\r' in a dotted-line |
| box. |
| |`show_tabs` |optional| |
| Whether tabs should be shown. |
| |`show_whitespace_errors`|optional| |
| Whether whitespace errors should be shown. |
| |`skip_deleted` |optional| |
| Whether deleted files should be skipped on file switch. |
| |`skip_uncommented` |optional| |
| Whether uncommented files should be skipped on file switch. |
| |`syntax_highlighting` |optional| |
| Whether syntax highlighting should be enabled. |
| |`tab_size` |optional| |
| Number of spaces that should be used to display one tab. |
| |===================================== |
| |
| [[query-limit-info]] |
| QueryLimitInfo |
| ~~~~~~~~~~~~~~ |
| The `QueryLimitInfo` entity contains information about the |
| link:access-control.html#capability_queryLimit[Query Limit] of a user. |
| |
| [options="header",width="50%",cols="1,6"] |
| |================================ |
| |Field Name |Description |
| |`min` |Lower limit. |
| |`max` |Upper limit. |
| |================================ |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |