50d3d9b892
The table of contents of the REST API documentation that lists the REST endpoints is currently very difficult to read because it contains too much information (method name, URL pattern and endpoint description for each endpoint). Simplify the format of the table of contents by only using the endpoint description as section header for the endpoints. The description normally provides the most value to the reader. The method name and the URL pattern are now formatted as a text box within each endpoint section. In addition the IDs that occur in the URL patterns are now linkified. Change-Id: I98f27be848df5188c9950698197ff523ec1b70de Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
338 lines
8.5 KiB
Plaintext
338 lines
8.5 KiB
Plaintext
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
|
|
---------
|
|
|
|
[[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,
|
|
"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
|
|
----
|
|
|
|
|
|
[[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.
|
|
|`startReplication` |not set if `false`|Whether the user has the
|
|
link:access-control.html#capability_startReplication[Start Replication]
|
|
capability.
|
|
|=================================
|
|
|
|
[[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]
|