Documentation/rest-api-accounts.txt

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
----


[[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.
|=================================

[[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]