Documentation/rest-api-plugins.txt

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.

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