blob: 579eacd740c7fb200d3d45fad9fc32353b1a07b9 [file] [log] [blame]
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",
"username": "john"
}
----
[[create-account]]
Create Account
~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#username[\{username\}]'
Creates a new account.
In the request body additional data for the account can be provided as
link:#account-input[AccountInput].
.Request
----
PUT /accounts/john HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"name": "John Doe",
"email": "john.doe@example.com",
"ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw==",
"http_password": "19D9aIn7zePb",
"groups": [
"MyProject-Owners"
]
}
----
As response a detailed link:#account-info[AccountInfo] entity is
returned that describes the created account.
.Response
----
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"_account_id": 1000195,
"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.
[[username]]
\{username\}
~~~~~~~~~~~~
The user name.
[[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.
|`username` |optional|The username of the user. +
Only set if detailed account information is requested.
|===========================
[[account-input]]
AccountInput
~~~~~~~~~~~~
The `AccountInput` entity contains information for the creation of
a new account.
[options="header",width="50%",cols="1,^2,4"]
|============================
|Field Name ||Description
|`username` |optional|
The user name. If provided, must match the user name from the URL.
|`name` |optional|The full name of the user.
|`email` |optional|The email address of the user.
|`ssh_key` |optional|The public SSH key of the user.
|`http_password`|optional|The HTTP password of the user.
|`groups` |optional|
A list of link:rest-api-groups.html#group-id[group IDs] that identify
the groups to which the user should be added.
|============================
[[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]