| = Gerrit Code Review - /plugins/ REST API |
| |
| This page describes the plugin related REST endpoints. |
| Please also take note of the general information on the |
| link:rest-api.html[REST API]. |
| |
| [[plugin-endpoints]] |
| == Plugin Endpoints |
| |
| Gerrit REST endpoints for installed plugins are available under |
| '/plugins/link:#plugin-id[\{plugin-id\}]/gerrit~<endpoint-id>'. |
| The `gerrit~` prefix ensures that the Gerrit REST endpoints for plugins |
| do not clash with any REST endpoint that a plugin may offer under its |
| namespace. |
| |
| |
| [[list-plugins]] |
| === List Plugins |
| -- |
| 'GET /plugins/' |
| -- |
| |
| Lists the plugins installed on the Gerrit server. Only the enabled |
| plugins are returned unless the `all` option is specified. |
| |
| To be allowed to see the installed plugins, a user must be a member of |
| a group that is granted the 'View Plugins' capability or the |
| 'Administrate Server' capability. |
| |
| As result a map is returned that maps the plugin IDs to |
| link:#plugin-info[PluginInfo] entries. The entries in the map are sorted |
| by plugin ID. |
| |
| .Request |
| ---- |
| GET /plugins/?all HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "delete-project": { |
| "kind": "gerritcodereview#plugin", |
| "id": "delete-project", |
| "index_url": "plugins/delete-project/", |
| "version": "2.9-SNAPSHOT" |
| }, |
| "reviewers-by-blame": { |
| "kind": "gerritcodereview#plugin", |
| "id": "reviewers-by-blame", |
| "index_url": "plugins/reviewers-by-blame/", |
| "version": "2.9-SNAPSHOT", |
| "disabled": true |
| } |
| } |
| ---- |
| |
| [[install-plugin]] |
| === Install Plugin |
| -- |
| 'PUT /plugins/link:#plugin-id[\{plugin-id\}]' |
| -- |
| |
| Installs a new plugin on the Gerrit server. If a plugin with the |
| specified name already exists it is overwritten. Note: if the plugin |
| provides its own name in the MANIFEST file, then the plugin name from |
| the MANIFEST file has precedence over the \{plugin-id\} above. |
| |
| The plugin jar can either be sent as binary data in the request body |
| or a URL to the plugin jar must be provided in the request body inside |
| a link:#plugin-input[PluginInput] entity. |
| |
| .Request |
| ---- |
| PUT /plugins/delete-project HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "url": "file:///gerrit/plugins/delete-project/delete-project-2.8.jar" |
| } |
| ---- |
| |
| To provide the plugin jar as binary data in the request body the |
| following curl command can be used: |
| |
| ---- |
| curl --digest --user admin:TNNuLkWsIV8w -X PUT --data-binary @delete-project-2.8.jar 'http://gerrit:8080/a/plugins/delete-project' |
| ---- |
| |
| As response a link:#plugin-info[PluginInfo] entity is returned that |
| describes the plugin. |
| |
| .Response |
| ---- |
| HTTP/1.1 201 Created |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#plugin", |
| "id": "delete-project", |
| "version": "2.8" |
| } |
| ---- |
| |
| If an existing plugin was overwritten the response is "`200 OK`". |
| |
| [[get-plugin-status]] |
| === Get Plugin Status |
| -- |
| 'GET /plugins/link:#plugin-id[\{plugin-id\}]/gerrit~status' |
| -- |
| |
| Retrieves the status of a plugin on the Gerrit server. |
| |
| .Request |
| ---- |
| GET /plugins/delete-project/gerrit~status HTTP/1.0 |
| ---- |
| |
| As response a link:#plugin-info[PluginInfo] entity is returned that |
| describes the plugin. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#plugin", |
| "id": "delete-project", |
| "version": "2.8" |
| } |
| ---- |
| |
| [[enable-plugin]] |
| === Enable Plugin |
| -- |
| 'POST /plugins/link:#plugin-id[\{plugin-id\}]/gerrit~enable' |
| -- |
| |
| Enables a plugin on the Gerrit server. |
| |
| .Request |
| ---- |
| POST /plugins/delete-project/gerrit~enable HTTP/1.0 |
| ---- |
| |
| As response a link:#plugin-info[PluginInfo] entity is returned that |
| describes the plugin. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#plugin", |
| "id": "delete-project", |
| "version": "2.8" |
| } |
| ---- |
| |
| [[disable-plugin]] |
| === Disable Plugin |
| -- |
| 'POST /plugins/link:#plugin-id[\{plugin-id\}]/gerrit~disable' |
| -- |
| |
| OR |
| |
| -- |
| 'DELETE /plugins/link:#plugin-id[\{plugin-id\}]' |
| -- |
| |
| Disables a plugin on the Gerrit server. |
| |
| .Request |
| ---- |
| POST /plugins/delete-project/gerrit~disable HTTP/1.0 |
| ---- |
| |
| As response a link:#plugin-info[PluginInfo] entity is returned that |
| describes the plugin. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#plugin", |
| "id": "delete-project", |
| "version": "2.8", |
| "disabled": true |
| } |
| ---- |
| |
| [[reload-plugin]] |
| === Reload Plugin |
| -- |
| 'POST /plugins/link:#plugin-id[\{plugin-id\}]/gerrit~reload' |
| -- |
| |
| Reloads a plugin on the Gerrit server. |
| |
| .Request |
| ---- |
| POST /plugins/delete-project/gerrit~reload HTTP/1.0 |
| ---- |
| |
| As response a link:#plugin-info[PluginInfo] entity is returned that |
| describes the plugin. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "kind": "gerritcodereview#plugin", |
| "id": "delete-project", |
| "version": "2.8", |
| "disabled": true |
| } |
| ---- |
| |
| |
| [[ids]] |
| == IDs |
| |
| [[plugin-id]] |
| === \{plugin-id\} |
| The ID of the plugin. |
| |
| [[json-entities]] |
| == JSON Entities |
| |
| [[plugin-info]] |
| === PluginInfo |
| The `PluginInfo` entity describes a plugin. |
| |
| [options="header",width="50%",cols="1,^2,4"] |
| |======================= |
| |Field Name ||Description |
| |`kind` ||`gerritcodereview#plugin` |
| |`id` ||The ID of the plugin. |
| |`version` ||The version of the plugin. |
| |`index_url`|optional|URL of the plugin's default page. |
| |`disabled` |not set if `false`|Whether the plugin is disabled. |
| |======================= |
| |
| [[plugin-input]] |
| === PluginInput |
| The `PluginInput` entity describes a plugin that should be installed. |
| |
| [options="header",width="50%",cols="1,6"] |
| |====================== |
| |Field Name|Description |
| |`url` |URL to the plugin jar. |
| |====================== |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |