| = Gerrit Code Review - /config/ REST API |
| |
| This page describes the config related REST endpoints. |
| Please also take note of the general information on the |
| link:rest-api.html[REST API]. |
| |
| [[config-endpoints]] |
| Config Endpoints |
| --------------- |
| |
| [[get-version]] |
| === Get Version |
| -- |
| 'GET /config/server/version' |
| -- |
| |
| Returns the version of the Gerrit server. |
| |
| .Request |
| ---- |
| GET /config/server/version HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "2.7" |
| ---- |
| |
| [[get-info]] |
| === Get Server Info |
| -- |
| 'GET /config/server/info' |
| -- |
| |
| Returns the information about the Gerrit server configuration. |
| |
| .Request |
| ---- |
| GET /config/server/info HTTP/1.0 |
| ---- |
| |
| As result a link:#server-info[ServerInfo] entity is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "auth": { |
| "auth_type": "LDAP", |
| "editable_account_fields": [ |
| "FULL_NAME", |
| "REGISTER_NEW_EMAIL" |
| ] |
| }, |
| "download": { |
| "schemes": [ |
| "anonymous http": { |
| "url": "http://gerrithost:8080/${project}", |
| "commands": { |
| "Checkout": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD", |
| "Format Patch": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", |
| "Pull": "git pull http://gerrithost:8080/${project} ${ref}", |
| "Cherry Pick": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD" |
| }, |
| "clone_commands": { |
| "Clone": "git clone http://gerrithost:8080/${project}" |
| "Clone with commit-msg hook": "git clone http://gerrithost:8080/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/" |
| } |
| }, |
| "http": { |
| "url": "http://jdoe@gerrithost:8080/${project}", |
| "is_auth_required": true, |
| "is_auth_supported": true, |
| "commands": { |
| "Checkout": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD", |
| "Format Patch": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", |
| "Pull": "git pull http://jdoe@gerrithost:8080/${project} ${ref}", |
| "Cherry Pick": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD" |
| }, |
| "clone_commands": { |
| "Clone": "git clone http://jdoe@gerrithost:8080/${project}", |
| "Clone with commit-msg hook": "git clone http://jdoe@gerrithost:8080/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/" |
| } |
| }, |
| "ssh": { |
| "url": "ssh://jdoe@gerrithost:29418/${project}", |
| "is_auth_required": true, |
| "is_auth_supported": true, |
| "commands": { |
| "Checkout": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD", |
| "Format Patch": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", |
| "Pull": "git pull ssh://jdoe@gerrithost:29418/${project} ${ref}", |
| "Cherry Pick": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD" |
| }, |
| "clone_commands": { |
| "Clone": "git clone ssh://jdoe@gerrithost:29418/${project}", |
| "Clone with commit-msg hook": "git clone ssh://jdoe@gerrithost:29418/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/" |
| } |
| } |
| ], |
| "archives": [ |
| "tgz", |
| "tar", |
| "tbz2", |
| "txz" |
| ] |
| }, |
| "gerrit": { |
| "all_projects": "All-Projects", |
| "all_users": "All-Users" |
| }, |
| "sshd": {}, |
| "suggest": { |
| "from": 0 |
| }, |
| "user": { |
| "anonymous_coward_name": "Anonymous Coward" |
| } |
| } |
| ---- |
| |
| [[confirm-email]] |
| === Confirm Email |
| -- |
| 'PUT /config/server/email.confirm' |
| -- |
| |
| Confirms that the user owns an email address. |
| |
| The email token must be provided in the request body inside |
| an link:#email-confirmation-input[EmailConfirmationInput] entity. |
| |
| .Request |
| ---- |
| PUT /config/server/email.confirm HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "token": "Enim+QNbAo6TV8Hur8WwoUypI6apG7qBPvF+bw==$MTAwMDAwNDp0ZXN0QHRlc3QuZGU=" |
| } |
| ---- |
| |
| The response is "`204 No Content`". |
| |
| If the token is invalid or if it's the token of another user the |
| request fails and the response is "`422 Unprocessable Entity`". |
| |
| |
| [[list-caches]] |
| === List Caches |
| -- |
| 'GET /config/server/caches/' |
| -- |
| |
| Lists the caches of the server. Caches defined by plugins are included. |
| |
| The caller must be a member of a group that is granted one of the |
| following capabilities: |
| |
| * link:access-control.html#capability_viewCaches[View Caches] |
| * link:access-control.html#capability_maintainServer[Maintain Server] |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| |
| As result a map of link:#cache-info[CacheInfo] entities is returned. |
| |
| The entries in the map are sorted by cache name. |
| |
| .Request |
| ---- |
| GET /config/server/caches/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "accounts": { |
| "type": "MEM", |
| "entries": { |
| "mem": 4 |
| }, |
| "average_get": "2.5ms", |
| "hit_ratio": { |
| "mem": 94 |
| } |
| }, |
| "accounts_byemail": { |
| "type": "MEM", |
| "entries": { |
| "mem": 4 |
| }, |
| "average_get": "771.8us", |
| "hit_ratio": { |
| "mem": 95 |
| } |
| }, |
| "accounts_byname": { |
| "type": "MEM", |
| "entries": { |
| "mem": 4 |
| }, |
| "hit_ratio": { |
| "mem": 100 |
| } |
| }, |
| "adv_bases": { |
| "type": "MEM", |
| "entries": {}, |
| "hit_ratio": {} |
| }, |
| "change_kind": { |
| "type": "DISK", |
| "entries": { |
| "space": "0.00k" |
| }, |
| "hit_ratio": {} |
| }, |
| "changes": { |
| "type": "MEM", |
| "entries": {}, |
| "hit_ratio": {} |
| }, |
| "conflicts": { |
| "type": "DISK", |
| "entries": { |
| "mem": 2, |
| "disk": 3, |
| "space": "2.75k" |
| }, |
| "hit_ratio": { |
| "mem": 0, |
| "disk": 100 |
| } |
| }, |
| "diff": { |
| "type": "DISK", |
| "entries": { |
| "mem": 177, |
| "disk": 253, |
| "space": "170.97k" |
| }, |
| "average_get": "1.1ms", |
| "hit_ratio": { |
| "mem": 67, |
| "disk": 100 |
| } |
| }, |
| "diff_intraline": { |
| "type": "DISK", |
| "entries": { |
| "mem": 1, |
| "disk": 1, |
| "space": "0.37k" |
| }, |
| "average_get": "6.8ms", |
| "hit_ratio": { |
| "mem": 0 |
| } |
| }, |
| "git_tags": { |
| "type": "DISK", |
| "entries": { |
| "space": "0.00k" |
| }, |
| "hit_ratio": {} |
| }, |
| groups": { |
| "type": "MEM", |
| "entries": { |
| "mem": 27 |
| }, |
| "average_get": "183.2us", |
| "hit_ratio": { |
| "mem": 12 |
| } |
| }, |
| "groups_byinclude": { |
| "type": "MEM", |
| "entries": {}, |
| "hit_ratio": {} |
| }, |
| "groups_byname": { |
| "type": "MEM", |
| "entries": {}, |
| "hit_ratio": {} |
| }, |
| "groups_byuuid": { |
| "type": "MEM", |
| "entries": { |
| "mem": 25 |
| }, |
| "average_get": "173.4us", |
| "hit_ratio": { |
| "mem": 13 |
| } |
| }, |
| "groups_external": { |
| "type": "MEM", |
| "entries": {}, |
| "hit_ratio": {} |
| }, |
| groups_members": { |
| "type": "MEM", |
| "entries": { |
| "mem": 4 |
| }, |
| "average_get": "697.8us", |
| "hit_ratio": { |
| "mem": 82 |
| } |
| }, |
| "permission_sort": { |
| "type": "MEM", |
| "entries": { |
| "mem": 16 |
| }, |
| "hit_ratio": { |
| "mem": 96 |
| } |
| }, |
| "plugin_resources": { |
| "type": "MEM", |
| "entries": { |
| "mem": 2 |
| }, |
| "hit_ratio": { |
| "mem": 83 |
| } |
| }, |
| "project_list": { |
| "type": "MEM", |
| "entries": { |
| "mem": 1 |
| }, |
| "average_get": "18.6ms", |
| "hit_ratio": { |
| "mem": 0 |
| } |
| }, |
| "projects": { |
| "type": "MEM", |
| "entries": { |
| "mem": 35 |
| }, |
| "average_get": "8.6ms", |
| "hit_ratio": { |
| "mem": 99 |
| } |
| }, |
| "quota-repo_size": { |
| "type": "DISK", |
| "entries": { |
| "space": "0.00k" |
| }, |
| "hit_ratio": {} |
| }, |
| "sshkeys": { |
| "type": "MEM", |
| "entries": { |
| "mem": 1 |
| }, |
| "average_get": "3.2ms", |
| "hit_ratio": { |
| "mem": 50 |
| } |
| }, |
| "web_sessions": { |
| "type": "DISK", |
| "entries": { |
| "mem": 1, |
| "disk": 2, |
| "space": "0.78k" |
| }, |
| "hit_ratio": { |
| "mem": 82 |
| } |
| } |
| } |
| ---- |
| |
| It is possible to get different output formats by specifying the |
| `format` option: |
| |
| * `LIST`: |
| + |
| Returns the cache names as JSON list. |
| + |
| The cache names are alphabetically sorted. |
| + |
| .Request |
| ---- |
| GET /config/server/caches/?format=LIST HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| "accounts", |
| "accounts_byemail", |
| "accounts_byname", |
| "adv_bases", |
| "change_kind", |
| "changes", |
| "conflicts", |
| "diff", |
| "diff_intraline", |
| "git_tags", |
| "groups", |
| "groups_byinclude", |
| "groups_byname", |
| "groups_byuuid", |
| "groups_external", |
| "groups_members", |
| "permission_sort", |
| "plugin_resources", |
| "project_list", |
| "projects", |
| "quota-repo_size", |
| "sshkeys", |
| "web_sessions" |
| ] |
| ---- |
| |
| * `TEXT_LIST`: |
| + |
| Returns the cache names as a UTF-8 list that is base64 encoded. The |
| cache names are delimited by '\n'. |
| + |
| The cache names are lexicographically sorted. |
| + |
| .Request |
| ---- |
| GET /config/server/caches/?format=TEXT_LIST HTTP/1.0 |
| ---- |
| + |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: text/plain; charset=UTF-8 |
| |
| YWNjb3VudHMKYW...ViX3Nlc3Npb25z |
| ---- |
| + |
| E.g. this could be used to flush all caches: |
| + |
| ---- |
| for c in $(curl --digest --user jdoe:TNAuLkXsIV7w http://gerrit/a/config/server/caches/?format=TEXT_LIST | base64 -D) |
| do |
| curl --digest --user jdoe:TNAuLkXsIV7w -X POST http://gerrit/a/config/server/caches/$c/flush |
| done |
| ---- |
| |
| [[cache-operations]] |
| === Cache Operations |
| -- |
| 'POST /config/server/caches/' |
| -- |
| |
| Executes a cache operation that is specified in the request body in a |
| link:#cache-operation-input[CacheOperationInput] entity. |
| |
| [[flush-all-caches]] |
| ==== Flush All Caches |
| |
| .Request |
| ---- |
| POST /config/server/caches/ HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "operation": "FLUSH_ALL" |
| } |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| ---- |
| |
| [[flush-several-caches]] |
| ==== Flush Several Caches At Once |
| |
| .Request |
| ---- |
| POST /config/server/caches/ HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "operation": "FLUSH", |
| "caches": [ |
| "projects", |
| "project_list" |
| ] |
| } |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| ---- |
| |
| [[get-cache]] |
| === Get Cache |
| -- |
| 'GET /config/server/caches/link:#cache-name[\{cache-name\}]' |
| -- |
| |
| Retrieves information about a cache. |
| |
| The caller must be a member of a group that is granted one of the |
| following capabilities: |
| |
| * link:access-control.html#capability_viewCaches[View Caches] |
| * link:access-control.html#capability_maintainServer[Maintain Server] |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| |
| As result a link:#cache-info[CacheInfo] entity is returned. |
| |
| .Request |
| ---- |
| GET /config/server/caches/projects HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "name": "projects", |
| "type": "MEM", |
| "entries": { |
| "mem": 35 |
| }, |
| "average_get": " 8.6ms", |
| "hit_ratio": { |
| "mem": 99 |
| } |
| } |
| ---- |
| |
| [[flush-cache]] |
| === Flush Cache |
| -- |
| 'POST /config/server/caches/link:#cache-name[\{cache-name\}]/flush' |
| -- |
| |
| Flushes a cache. |
| |
| The caller must be a member of a group that is granted one of the |
| following capabilities: |
| |
| * link:access-control.html#capability_flushCaches[Flush Caches] (any cache |
| except "web_sessions") |
| * link:access-control.html#capability_maintainServer[Maintain Server] (any cache |
| including "web_sessions") |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| (any cache including "web_sessions") |
| |
| .Request |
| ---- |
| POST /config/server/caches/projects/flush HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| ---- |
| |
| [[get-summary]] |
| === Get Summary |
| -- |
| 'GET /config/server/summary' |
| -- |
| |
| Retrieves a summary of the current server state. |
| |
| The caller must be a member of a group that is granted the |
| link:access-control.html#capability_administrateServer[Administrate |
| Server] capability. |
| |
| The following options are supported: |
| |
| * `jvm`: |
| + |
| Includes a JVM summary. |
| |
| * `gc`: |
| + |
| Requests a Java garbage collection before computing the information |
| about the Java memory heap. |
| |
| .Request |
| ---- |
| GET /config/server/summary?jvm HTTP/1.0 |
| ---- |
| |
| As result a link:#summary-info[SummaryInfo] entity is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "task_summary": { |
| "total": 2, |
| "sleeping": 2 |
| }, |
| "mem_summary": { |
| "total": "341.06m", |
| "used": "57.16m", |
| "free": "283.90m", |
| "buffers": "0.00k", |
| "max": "1.67g", |
| } |
| "thread_summary": { |
| "cpus": 8, |
| "threads": 44, |
| "counts": { |
| "HTTP": { |
| "RUNNABLE": 3, |
| "TIMED_WAITING": 2 |
| }, |
| "SSH-Interactive-Worker": { |
| "WAITING": 1 |
| }, |
| "Other": { |
| "WAITING": 10, |
| "RUNNABLE": 2, |
| "TIMED_WAITING": 25 |
| }, |
| "SshCommandStart": { |
| "WAITING": 1 |
| } |
| } |
| }, |
| "jvm_summary": { |
| "vm_vendor": "Oracle Corporation", |
| "vm_name": "Java HotSpot(TM) 64-Bit Server VM", |
| "vm_version": "23.25-b01", |
| "os_name": "Mac OS X", |
| "os_version": "10.8.5", |
| "os_arch": "x86_64", |
| "user": "gerrit", |
| "host": "GERRIT", |
| "current_working_directory": "/Users/gerrit/site", |
| "site": "/Users/gerrit/site" |
| } |
| } |
| ---- |
| |
| [[list-capabilities]] |
| === List Capabilities |
| -- |
| 'GET /config/server/capabilities' |
| -- |
| |
| Lists the capabilities that are available in the system. There are two |
| kinds of capabilities: core and plugin-owned capabilities. |
| |
| As result a map of link:#capability-info[CapabilityInfo] entities is |
| returned. |
| |
| The entries in the map are sorted by capability ID. |
| |
| .Request |
| ---- |
| GET /config/server/capabilities/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "accessDatabase": { |
| "id": "accessDatabase", |
| "name": "Access Database" |
| }, |
| "administrateServer": { |
| "id": "administrateServer", |
| "name": "Administrate Server" |
| }, |
| "createAccount": { |
| "id": "createAccount", |
| "name": "Create Account" |
| }, |
| "createGroup": { |
| "id": "createGroup", |
| "name": "Create Group" |
| }, |
| "createProject": { |
| "id": "createProject", |
| "name": "Create Project" |
| }, |
| "emailReviewers": { |
| "id": "emailReviewers", |
| "name": "Email Reviewers" |
| }, |
| "flushCaches": { |
| "id": "flushCaches", |
| "name": "Flush Caches" |
| }, |
| "killTask": { |
| "id": "killTask", |
| "name": "Kill Task" |
| }, |
| "priority": { |
| "id": "priority", |
| "name": "Priority" |
| }, |
| "queryLimit": { |
| "id": "queryLimit", |
| "name": "Query Limit" |
| }, |
| "runGC": { |
| "id": "runGC", |
| "name": "Run Garbage Collection" |
| }, |
| "streamEvents": { |
| "id": "streamEvents", |
| "name": "Stream Events" |
| }, |
| "viewCaches": { |
| "id": "viewCaches", |
| "name": "View Caches" |
| }, |
| "viewConnections": { |
| "id": "viewConnections", |
| "name": "View Connections" |
| }, |
| "viewPlugins": { |
| "id": "viewPlugins", |
| "name": "View Plugins" |
| }, |
| "viewQueue": { |
| "id": "viewQueue", |
| "name": "View Queue" |
| } |
| } |
| ---- |
| |
| [[list-tasks]] |
| === List Tasks |
| -- |
| 'GET /config/server/tasks/' |
| -- |
| |
| Lists the tasks from the background work queues that the Gerrit daemon |
| is currently performing, or will perform in the near future. |
| |
| Gerrit contains an internal scheduler, similar to cron, that it uses to |
| queue and dispatch both short and long term tasks. |
| |
| Tasks that are completed or canceled exit the queue very quickly once |
| they enter this state, but it can be possible to observe tasks in these |
| states. |
| |
| End-users may see a task only if they can also see the project the task |
| is associated with. Tasks operating on other projects, or that do not |
| have a specific project, are hidden. |
| |
| The caller must be a member of a group that is granted one of the |
| following capabilities: |
| |
| * link:access-control.html#capability_viewQueue[View Queue] |
| * link:access-control.html#capability_maintainServer[Maintain Server] |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| |
| As result a list of link:#task-info[TaskInfo] entities is returned. |
| |
| The entries in the list are sorted by task state, remaining delay and |
| command. |
| |
| .Request |
| ---- |
| GET /config/server/tasks/ HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "id": "1e688bea", |
| "state": "SLEEPING", |
| "start_time": "2014-06-11 12:58:51.991000000", |
| "delay": 3453, |
| "command": "Reload Submit Queue" |
| }, |
| { |
| "id": "3e6d4ffa", |
| "state": "SLEEPING", |
| "start_time": "2014-06-11 12:58:51.508000000", |
| "delay": 3287966, |
| "command": "Log File Compressor" |
| } |
| ] |
| ---- |
| |
| [[get-task]] |
| === Get Task |
| -- |
| 'GET /config/server/tasks/link:#task-id[\{task-id\}]' |
| -- |
| |
| Retrieves a task from the background work queue that the Gerrit daemon |
| is currently performing, or will perform in the near future. |
| |
| End-users may see a task only if they can also see the project the task |
| is associated with. Tasks operating on other projects, or that do not |
| have a specific project, are hidden. |
| |
| The caller must be a member of a group that is granted one of the |
| following capabilities: |
| |
| * link:access-control.html#capability_viewQueue[View Queue] |
| * link:access-control.html#capability_maintainServer[Maintain Server] |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| |
| As result a link:#task-info[TaskInfo] entity is returned. |
| |
| .Request |
| ---- |
| GET /config/server/tasks/1e688bea HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "1e688bea", |
| "state": "SLEEPING", |
| "start_time": "2014-06-11 12:58:51.991000000", |
| "delay": 3453, |
| "command": "Reload Submit Queue" |
| } |
| ---- |
| |
| [[delete-task]] |
| === Delete Task |
| -- |
| 'DELETE /config/server/tasks/link:#task-id[\{task-id\}]' |
| -- |
| |
| Kills a task from the background work queue that the Gerrit daemon |
| is currently performing, or will perform in the near future. |
| |
| The caller must be a member of a group that is granted one of the |
| following capabilities: |
| |
| * link:access-control.html#capability_kill[Kill Task] |
| * link:access-control.html#capability_maintainServer[Maintain Server] |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| |
| End-users may see a task only if they can also see the project the task |
| is associated with. Tasks operating on other projects, or that do not |
| have a specific project, are hidden. |
| |
| Members of a group granted one of the following capabilities may view |
| all tasks: |
| |
| * link:access-control.html#capability_viewQueue[View Queue] |
| * link:access-control.html#capability_maintainServer[Maintain Server] |
| * link:access-control.html#capability_administrateServer[Administrate Server] |
| |
| .Request |
| ---- |
| DELETE /config/server/tasks/1e688bea HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-top-menus]] |
| === Get Top Menus |
| -- |
| 'GET /config/server/top-menus' |
| -- |
| |
| Returns the list of additional top menu entries. |
| |
| .Request |
| ---- |
| GET /config/server/top-menus HTTP/1.0 |
| ---- |
| |
| As response a list of the additional top menu entries as |
| link:#top-menu-entry-info[TopMenuEntryInfo] entities is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "name": "Top Menu Entry", |
| "items": [ |
| { |
| "url": "http://gerrit.googlecode.com/", |
| "name": "Gerrit", |
| "target": "_blank" |
| } |
| ] |
| } |
| ] |
| ---- |
| |
| |
| [[ids]] |
| == IDs |
| |
| [[cache-name]] |
| === \{cache-name\} |
| The name of the cache. |
| |
| If the cache is defined by a plugin the cache name must include the |
| plugin name: "<plugin-name>-<cache-name>". |
| |
| Gerrit core caches can optionally be prefixed with "gerrit": |
| "gerrit-<cache-name>". |
| |
| [[task-id]] |
| === \{task-id\} |
| The ID of the task (hex string). |
| |
| |
| [[json-entities]] |
| == JSON Entities |
| |
| [[auth-info]] |
| === AuthInfo |
| The `AuthInfo` entity contains information about the authentication |
| configuration of the Gerrit server. |
| |
| [options="header",cols="1,^1,5"] |
| |========================================== |
| |Field Name ||Description |
| |`type` || |
| The link:config-gerrit.html#auth.type[authentication type] that is |
| configured on the server. Can be `OPENID`, `OPENID_SSO`, `OAUTH`, |
| `HTTP`, `HTTP_LDAP`, `CLIENT_SSL_CERT_LDAP`, `LDAP`, `LDAP_BIND`, |
| `CUSTOM_EXTENSION` or `DEVELOPMENT_BECOME_ANY_ACCOUNT`. |
| |`use_contributor_agreements` |not set if `false`| |
| Whether link:config-gerrit.html#auth.contributorAgreements[contributor |
| agreements] are required. |
| |`editable_account_fields` || |
| List of account fields that are editable. Possible values are |
| `FULL_NAME`, `USER_NAME` and `REGISTER_NEW_EMAIL`. |
| |`login_url` |optional| |
| The link:config-gerrit.html#auth.loginUrl[login URL]. Only set if |
| link:config-gerrit.html#auth.type[authentication type] is `HTTP` or |
| `HTTP_LDAP`. |
| |`login_text` |optional| |
| The link:config-gerrit.html#auth.loginText[login text]. Only set if |
| link:config-gerrit.html#auth.type[authentication type] is `HTTP` or |
| `HTTP_LDAP`. |
| |`switch_account_url` |optional| |
| The link:config-gerrit.html#auth.switchAccountUrl[URL to switch |
| accounts]. |
| |`register_url` |optional| |
| The link:config-gerrit.html#auth.registerUrl[register URL]. Only set if |
| link:config-gerrit.html#auth.type[authentication type] is `LDAP`, |
| `LDAP_BIND` or `CUSTOM_EXTENSION`. |
| |`register_text` |optional| |
| The link:config-gerrit.html#auth.registerText[register text]. Only set |
| if link:config-gerrit.html#auth.type[authentication type] is `LDAP`, |
| `LDAP_BIND` or `CUSTOM_EXTENSION`. |
| |`edit_full_name_url` |optional| |
| The link:config-gerrit.html#auth.editFullNameUrl[URL to edit the full |
| name]. Only set if link:config-gerrit.html#auth.type[authentication |
| type] is `LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`. |
| |`http_password_url` |optional| |
| The link:config-gerrit.html#auth.httpPasswordUrl[URL to obtain an HTTP |
| password]. Only set if link:config-gerrit.html#auth.type[authentication |
| type] is `CUSTOM_EXTENSION`. |
| |`is_git_basic_auth` |optional, not set if `false`| |
| Whether link:config-gerrit.html#auth.gitBasicAuth[basic authentication |
| is used for Git over HTTP/HTTPS]. Only set if |
| link:config-gerrit.html#auth.type[authentication type] is is `LDAP` or |
| `LDAP_BIND`. |
| |========================================== |
| |
| [[cache-info]] |
| === CacheInfo |
| The `CacheInfo` entity contains information about a cache. |
| |
| [options="header",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`name` | |
| not set if returned in a map where the cache name is used as map key| |
| The cache name. If the cache is defined by a plugin the cache name |
| includes the plugin name: "<plugin-name>-<cache-name>". |
| |`type` || |
| The type of the cache (`MEM`: in memory cache, `DISK`: disk cache). |
| |`entries` || |
| Information about the entries in the cache as a |
| link:#entries-info[EntriesInfo] entity. |
| |`average_get` |optional| |
| The average duration of getting one entry from the cache. The value is |
| returned with a standard time unit abbreviation (`ns`: nanoseconds, |
| `us`: microseconds, `ms`: milliseconds, `s`: seconds). |
| |`hit_ratio` || |
| Information about the hit ratio as a link:#hit-ration-info[ |
| HitRatioInfo] entity. |
| |================================== |
| |
| [[cache-operation-input]] |
| === CacheOperationInput |
| The `CacheOperationInput` entity contains information about an |
| operation that should be executed on caches. |
| |
| [options="header",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`operation` || |
| The cache operation that should be executed: |
| |
| `FLUSH_ALL`: Flushes all caches, except the `web_sessions` cache. |
| |
| `FLUSH`: Flushes the specified caches. |
| |`caches` |optional| |
| A list of cache names. This list defines the caches on which the |
| specified operation should be executed. Whether this list must be |
| specified depends on the operation being executed. |
| |================================== |
| |
| [[capability-info]] |
| === CapabilityInfo |
| The `CapabilityInfo` entity contains information about a capability. |
| |
| [options="header",cols="1,6"] |
| |================================= |
| |Field Name |Description |
| |`id` |capability ID |
| |`name` |capability name |
| |================================= |
| |
| [[change-config-info]] |
| === ChangeConfigInfo |
| The `ChangeConfigInfo` entity contains information about Gerrit |
| configuration from the link:config-gerrit.html#change[change] |
| section. |
| |
| [options="header",cols="1,^1,5"] |
| |============================= |
| |Field Name ||Description |
| |`allow_drafts` |not set if `false`| |
| link:config-gerrit.html#change.allowDrafts[Whether draft workflow is |
| allowed]. |
| |`large_change` || |
| link:config-gerrit.html#change.largeChange[Number of changed lines from |
| which on a change is considered as a large change]. |
| |`reply_label` || |
| link:config-gerrit.html#change.replyTooltip[Label name for the reply |
| button]. |
| |`reply_tooltip` || |
| link:config-gerrit.html#change.replyTooltip[Tooltip for the reply |
| button]. |
| |`update_delay` || |
| link:config-gerrit.html#change.updateDelay[How often in seconds the web |
| interface should poll for updates to the currently open change]. |
| |`submit_whole_topic` || |
| link:config-gerrit.html#change.submitWholeTopic[A configuration if |
| the whole topic is submitted]. |
| |============================= |
| |
| [[download-info]] |
| === DownloadInfo |
| The `DownloadInfo` entity contains information about supported download |
| options. |
| |
| [options="header",cols="1,6"] |
| |======================= |
| |Field Name |Description |
| |`schemes` | |
| The supported download schemes as a map which maps the scheme name to a |
| of link:#download-scheme-info[DownloadSchemeInfo] entity. |
| |`archives` | |
| List of supported archive formats. Possible values are `tgz`, `tar`, |
| `tbz2` and `txz`. |
| |======================= |
| |
| [[download-scheme-info]] |
| === DownloadSchemeInfo |
| The `DownloadSchemeInfo` entity contains information about a supported |
| download scheme and its commands. |
| |
| [options="header",cols="1,^1,5"] |
| |================================= |
| |Field Name ||Description |
| |`url` || |
| The URL of the download scheme, where '${project}' is used as |
| placeholder for the project name. |
| |`is_auth_required` |not set if `false`| |
| Whether this download scheme requires authentication. |
| |`is_auth_supported` |not set if `false`| |
| Whether this download scheme supports authentication. |
| |`commands` || |
| Download commands as a map which maps the command name to the download |
| command. In the download command '${project}' is used as |
| placeholder for the project name, and '${ref}' is used as |
| placeholder for the (change) ref. |
| |
| Empty, if accessed anonymously and the download scheme requires |
| authentication. |
| |`clone_commands` || |
| Clone commands as a map which maps the command name to the clone |
| command. In the clone command '${project}' is used as |
| placeholder for the project name and '${project-base-name}' as name |
| for the project base name (e.g. for a project 'foo/bar' '${project}' |
| is a placeholder for 'foo/bar' and '${project-base-name}' is a |
| placeholder for 'bar'). |
| |
| Empty, if accessed anonymously and the download scheme requires |
| authentication. |
| |================================= |
| |
| [[email-confirmation-input]] |
| === EmailConfirmationInput |
| The `EmailConfirmationInput` entity contains information for confirming |
| an email address. |
| |
| [options="header",cols="1,6"] |
| |======================= |
| |Field Name |Description |
| |`token` | |
| The token that was sent by mail to a newly registered email address. |
| |======================= |
| |
| [[entries-info]] |
| === EntriesInfo |
| The `EntriesInfo` entity contains information about the entries in a |
| cache. |
| |
| [options="header",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`mem` |optional|Number of cache entries that are held in memory. |
| |`disk` |optional|Number of cache entries on the disk. For non-disk |
| caches this value is not set; for disk caches it is only set if there |
| are entries in the cache. |
| |`space` |optional| |
| The space that is consumed by the cache on disk. The value is returned |
| with a unit abbreviation (`k`: kilobytes, `m`: megabytes, |
| `g`: gigabytes). Only set for disk caches. |
| |================================== |
| |
| [[gerrit-info]] |
| === GerritInfo |
| The `GerritInfo` entity contains information about Gerrit |
| configuration from the link:config-gerrit.html#gerrit[gerrit] section. |
| |
| [options="header",cols="1,^1,5"] |
| |================================= |
| |Field Name ||Description |
| |`all_projects_name` || |
| Name of the link:config-gerrit.html#gerrit.allProjects[root project]. |
| |`all_users_name` || |
| Name of the link:config-gerrit.html#gerrit.allUsers[project in which |
| meta data of all users is stored]. |
| |`doc_url` |optional| |
| Custom base URL where Gerrit server documentation is located. |
| (Documentation may still be available at /Documentation relative to the |
| Gerrit base path even if this value is unset.) |
| |`report_bug_url` |optional| |
| link:config-gerrit.html#gerrit.reportBugUrl[URL to report bugs]. |
| |`report_bug_text` |optional, not set if default| |
| link:config-gerrit.html#gerrit.reportBugText[Display text for report |
| bugs link]. |
| |================================= |
| |
| [[git-web-info]] |
| === GitwebInfo |
| The `GitwebInfo` entity contains information about the |
| link:config-gerrit.html#gitweb[gitweb] configuration. |
| |
| [options="header",cols="1,6"] |
| |======================= |
| |Field Name |Description |
| |`url` | |
| The link:config-gerrit.html#gitweb.url[gitweb base URL]. |
| |`type` | |
| The link:config-gerrit.html#gitweb.type[gitweb type] as |
| link:#git-web-type-info[GitwebTypeInfo] entity. |
| |======================= |
| |
| [[git-web-type-info]] |
| === GitwebTypeInfo |
| The `GitwebTypeInfo` entity contains information about the |
| link:config-gerrit.html#gitweb[gitweb] configuration. |
| |
| [options="header",cols="1,^1,5"] |
| |============================= |
| |Field Name ||Description |
| |`name` || |
| The link:config-gerrit.html#gitweb.linkname[gitweb link name]. |
| |`revision` |optional| |
| The link:config-gerrit.html#gitweb.revision[gitweb revision pattern]. |
| |`project` |optional| |
| The link:config-gerrit.html#gitweb.project[gitweb project pattern]. |
| |`branch` |optional| |
| The link:config-gerrit.html#gitweb.branch[gitweb branch pattern]. |
| |`root_tree` |optional| |
| The link:config-gerrit.html#gitweb.roottree[gitweb root tree pattern]. |
| |`file` |optional| |
| The link:config-gerrit.html#gitweb.file[gitweb file pattern]. |
| |`file_history` |optional| |
| The link:config-gerrit.html#gitweb.filehistory[gitweb file history |
| pattern]. |
| |`path_separator`|| |
| The link:config-gerrit.html#gitweb.pathSeparator[gitweb path separator]. |
| |`link_drafts` |optional| |
| link:config-gerrit.html#gitweb.linkDrafts[Whether Gerrit should provide |
| links to gitweb on draft patch set.] |
| |`url_encode` |optional| |
| link:config-gerrit.html#gitweb.urlEncode[Whether Gerrit should encode |
| the generated viewer URL.] |
| |============================= |
| |
| [[hit-ration-info]] |
| === HitRatioInfo |
| The `HitRatioInfo` entity contains information about the hit ratio of a |
| cache. |
| |
| [options="header",cols="1,^1,5"] |
| |================================== |
| |Field Name ||Description |
| |`mem` || |
| Hit ratio for cache entries that are held in memory (0 \<= value \<= 100). |
| |`disk` |optional| |
| Hit ratio for cache entries that are held on disk (0 \<= value \<= 100). |
| Only set for disk caches. |
| |================================== |
| |
| [[jvm-summary-info]] |
| === JvmSummaryInfo |
| The `JvmSummaryInfo` entity contains information about the JVM. |
| |
| [options="header",cols="1,^1,5"] |
| |======================================== |
| |Field Name ||Description |
| |`vm_vendor` ||The vendor of the virtual machine. |
| |`vm_name` ||The name of the virtual machine. |
| |`vm_version` ||The version of the virtual machine. |
| |`os_name` ||The name of the operating system. |
| |`os_version` ||The version of the operating system. |
| |`os_arch` ||The architecture of the operating system. |
| |`user` ||The user that is running Gerrit. |
| |`host` |optional| |
| The host on which Gerrit is running. |
| |`current_working_directory`||The current working directory. |
| |`site` ||The path to the review site. |
| |======================================== |
| |
| [[mem-summary-info]] |
| === MemSummaryInfo |
| The `MemSummaryInfo` entity contains information about the current |
| memory usage. |
| |
| [options="header",cols="1,^1,5"] |
| |============================ |
| |Field Name ||Description |
| |`total` || |
| The total size of the memory. The value is returned with a unit |
| abbreviation (`k`: kilobytes, `m`: megabytes, `g`: gigabytes). |
| |`used` || |
| The size of used memory. The value is returned with a unit abbreviation |
| (`k`: kilobytes, `m`: megabytes, `g`: gigabytes). |
| |`free` || |
| The size of free memory. The value is returned with a unit abbreviation |
| (`k`: kilobytes, `m`: megabytes, `g`: gigabytes). |
| |`buffers` || |
| The size of memory used for JGit buffers. The value is returned with a |
| unit abbreviation (`k`: kilobytes, `m`: megabytes, `g`: gigabytes). |
| |`max` || |
| The maximal memory size. The value is returned with a unit abbreviation |
| (`k`: kilobytes, `m`: megabytes, `g`: gigabytes). |
| |`open_files` |optional| |
| The number of open files. |
| |============================ |
| |
| [[plugin-config-info]] |
| === PluginConfigInfo |
| The `PluginConfigInfo` entity contains information about Gerrit |
| extensions by plugins. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================== |
| |Field Name ||Description |
| |`has_avatars` |not set if `false`| |
| Whether an avatar provider is registered. |
| |=========================== |
| |
| [[receive-info]] |
| === ReceiveInfo |
| The `ReceiveInfo` entity contains information about the configuration |
| of git-receive-pack behavior on the server. |
| |
| [options="header",cols="1,^1,5"] |
| |======================================= |
| |Field Name ||Description |
| |`enableSignedPush`|optional| |
| Whether signed push validation support is enabled on the server; see the |
| link:config-gerrit.html#receive.certNonceSeed[global configuration] for |
| details. |
| |======================================= |
| |
| [[server-info]] |
| === ServerInfo |
| The `ServerInfo` entity contains information about the configuration of |
| the Gerrit server. |
| |
| [options="header",cols="1,^1,5"] |
| |======================================= |
| |Field Name ||Description |
| |`auth` || |
| Information about the authentication configuration as |
| link:#auth-info[AuthInfo] entity. |
| |`change` || |
| Information about the configuration from the |
| link:config-gerrit.html#change[change] section as |
| link:#change-config-info[ChangeConfigInfo] entity. |
| |`download` || |
| Information about the configured download options as |
| link:#download-info[DownloadInfo] entity. |
| information about Gerrit |
| |`gerrit` || |
| Information about the configuration from the |
| link:config-gerrit.html#gerrit[gerrit] section as link:#gerrit-info[ |
| GerritInfo] entity. |
| |`gitweb ` |optional| |
| Information about the link:config-gerrit.html#gitweb[gitweb] |
| |`plugin ` || |
| Information about Gerrit extensions by plugins as |
| link:#plugin-config-info[PluginConfigInfo] entity. |
| |`receive` |optional| |
| Information about the receive-pack configuration as a |
| link:#receive-info[ReceiveInfo] entity. |
| |`sshd` |optional| |
| Information about the configuration from the |
| link:config-gerrit.html#sshd[sshd] section as link:#sshd-info[SshdInfo] |
| entity. Not set if SSHD is disabled. |
| |`suggest` || |
| Information about the configuration from the |
| link:config-gerrit.html#suggest[suggest] section as link:#suggest-info[ |
| SuggestInfo] entity. |
| |`url_aliases` |optional| |
| A map of URL aliases, where a regular expression for an URL token is |
| mapped to a target URL token. The target URL token can contain |
| placeholders for the groups matched by the regular expression: `$1` for |
| the first matched group, `$2` for the second matched group, etc. |
| |`user` || |
| Information about the configuration from the |
| link:config-gerrit.html#user[user] section as link:#user-config-info[ |
| UserConfigInfo] entity. |
| |======================================= |
| |
| [[sshd-info]] |
| === SshdInfo |
| The `SshdInfo` entity contains information about Gerrit |
| configuration from the link:config-gerrit.html#sshd[sshd] |
| section. |
| |
| This entity doesn't contain any data, but the presence of this (empty) |
| entity in the link:#server-info[ServerInfo] entity means that SSHD is |
| enabled on the server. |
| |
| [[suggest-info]] |
| === SuggestInfo |
| The `SuggestInfo` entity contains information about Gerrit |
| configuration from the link:config-gerrit.html#suggest[suggest] |
| section. |
| |
| [options="header",cols="1,6"] |
| |======================= |
| |Field Name |Description |
| |`from` | |
| The link:config-gerrit.html#suggest.from[number of characters] that a |
| user must have typed before suggestions are provided. |
| |======================= |
| |
| [[summary-info]] |
| === SummaryInfo |
| The `SummaryInfo` entity contains information about the current state |
| of the server. |
| |
| [options="header",cols="1,^1,5"] |
| |============================ |
| |Field Name ||Description |
| |`task_summary` || |
| Summary about current tasks as a link:#task-summary-info[ |
| TaskSummaryInfo] entity. |
| |`mem_summary` || |
| Summary about current memory usage as a link:#mem-summary-info[ |
| MemSummaryInfo] entity. |
| |`thread_summary` || |
| Summary about current threads as a link:#thread-summary-info[ |
| ThreadSummaryInfo] entity. |
| |`jvm_summary` |optional| |
| Summary about the JVM link:#jvm-summary-info[JvmSummaryInfo] entity. |
| Only set if the `jvm` option was set. |
| |============================ |
| |
| [[task-info]] |
| === TaskInfo |
| The `TaskInfo` entity contains information about a task in a background |
| work queue. |
| |
| [options="header",cols="1,^1,5"] |
| |==================================== |
| |Field Name ||Description |
| |`id` ||The ID of the task. |
| |`state` || |
| The state of the task, can be `DONE`, `CANCELLED`, `RUNNING`, `READY`, |
| `SLEEPING` and `OTHER`. |
| |`start_time` ||The start time of the task. |
| |`delay` ||The remaining delay of the task. |
| |`command` ||The command of the task. |
| |`remote_name`|optional| |
| The remote name. May only be set for tasks that are associated with a |
| project. |
| |`project` |optional|The project the task is associated with. |
| |==================================== |
| |
| [[task-summary-info]] |
| === TaskSummaryInfo |
| The `TaskSummaryInfo` entity contains information about the current |
| tasks. |
| |
| [options="header",cols="1,^1,5"] |
| |============================ |
| |Field Name ||Description |
| |`total` |optional| |
| Total number of current tasks. |
| |`running` |optional| |
| Number of currently running tasks. |
| |`ready` |optional| |
| Number of currently ready tasks. |
| |`sleeping` |optional| |
| Number of currently sleeping tasks. |
| |============================ |
| |
| [[thread-summary-info]] |
| === ThreadSummaryInfo |
| The `ThreadSummaryInfo` entity contains information about the current |
| threads. |
| |
| [options="header",cols="1,6"] |
| |=========================== |
| |Field Name |Description |
| |`cpus` | |
| The number of available processors. |
| |`threads` | |
| The total number of current threads. |
| |`counts` | |
| Detailed thread counts as a map that maps a thread kind to a map that |
| maps a thread state to the thread count. The thread kinds group the |
| counts by threads that have the same name prefix (`HTTP`, |
| `IntraLineDiff`, `ReceiveCommits`, `SSH git-receive-pack`, |
| `SSH git-upload-pack`, `SSH-Interactive-Worker`, `SSH-Stream-Worker`, |
| `SshCommandStart`). The counts for other threads are available under |
| the thread kind `Other`. Counts for the following thread states can be |
| included: `NEW`, `RUNNABLE`, `BLOCKED`, `WAITING`, `TIMED_WAITING` and |
| `TERMINATED`. |
| |=========================== |
| |
| [[top-menu-entry-info]] |
| === TopMenuEntryInfo |
| The `TopMenuEntryInfo` entity contains information about a top menu |
| entry. |
| |
| [options="header",cols="1,6"] |
| |================================= |
| |Field Name |Description |
| |`name` |Name of the top menu entry. |
| |`items` |List of link:#top-menu-item-info[menu items]. |
| |================================= |
| |
| [[top-menu-item-info]] |
| === TopMenuItemInfo |
| The `TopMenuItemInfo` entity contains information about a menu item in |
| a top menu entry. |
| |
| [options="header",cols="1,^1,5"] |
| |======================== |
| |Field Name ||Description |
| |`url` ||The URL of the menu item link. |
| |`name` ||The name of the menu item. |
| |`target` ||Target attribute of the menu item link. |
| |`id` |optional|The `id` attribute of the menu item link. |
| |======================== |
| |
| [[user-config-info]] |
| === UserConfigInfo |
| The `UserConfigInfo` entity contains information about Gerrit |
| configuration from the link:config-gerrit.html#user[user] section. |
| |
| [options="header",cols="1,6"] |
| |==================================== |
| |Field Name |Description |
| |`anonymous_coward_name` | |
| link:config-gerrit.html#user.anonymousCoward[Username] that is |
| displayed in the Gerrit Web UI and in e-mail notifications if the full |
| name of the user is not set. |
| |==================================== |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |
