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.

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/ HTTP/1.0
----

.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "delete-project": {
      "id": "delete-project",
      "index_url": "plugins/delete-project/",
      "filename": "delete-project.jar",
      "api_version": "2.9.3-SNAPSHOT",
      "version": "2.9-SNAPSHOT"
    }
  }
----

[[plugin-options]]
==== Plugin Options
All(a)::
List all plugins including those that are disabled.

.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": {
      "id": "delete-project",
      "index_url": "plugins/delete-project/",
      "filename": "delete-project.jar",
      "version": "2.9-SNAPSHOT"
    },
    "reviewers-by-blame": {
      "id": "reviewers-by-blame",
      "index_url": "plugins/reviewers-by-blame/",
      "filename": "reviewers-by-blame.jar",
      "version": "2.9-SNAPSHOT",
      "disabled": true
    }
  }
----

Limit(n)::
Limit the number of plugins to be included in the results.
+
Query the first plugin in the plugin list:
+
.Request
----
  GET /plugins/?n=1 HTTP/1.0
----
+
.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "delete-project": {
      "id": "delete-project",
      "index_url": "plugins/delete-project/",
      "filename": "delete-project.jar",
      "version": "2.9-SNAPSHOT"
    }
  }
----

Prefix(p)::
Limit the results to those plugins that start with the specified
prefix.
+
The match is case sensitive. May not be used together with `m` or `r`.
+
List all plugins that start with `delete`:
+
.Request
----
  GET /plugins/?p=delete HTTP/1.0
----
+
.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "delete-project": {
      "id": "delete-project",
      "index_url": "plugins/delete-project/",
      "filename": "delete-project.jar",
      "version": "2.9-SNAPSHOT"
    }
  }
----
+
E.g. this feature can be used by suggestion client UI's to limit results.

Regex(r)::
Limit the results to those plugins that match the specified regex.
+
Boundary matchers '^' and '$' are implicit. For example: the regex 'test.*' will
match any plugins that start with 'test' and regex '.*test' will match any
project that end with 'test'.
+
The match is case sensitive. May not be used together with `m` or `p`.
+
List all plugins that match regex `some.*plugin`:
+
.Request
----
  GET /plugins/?r=some.*plugin HTTP/1.0
----
+
.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "some-plugin": {
      "id": "some-plugin",
      "index_url": "plugins/some-plugin/",
      "filename": "some-plugin.jar",
      "version": "2.9-SNAPSHOT"
    },
    "some-other-plugin": {
      "id": "some-other-plugin",
      "index_url": "plugins/some-other-plugin/",
      "filename": "some-other-plugin.jar",
      "version": "2.9-SNAPSHOT"
    }
  }

----

Skip(S)::
Skip the given number of plugins from the beginning of the list.
+
Query the second plugin in the plugin list:
+
.Request
----
  GET /plugins/?all&n=1&S=1 HTTP/1.0
----
+
.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "reviewers-by-blame": {
      "id": "reviewers-by-blame",
      "index_url": "plugins/reviewers-by-blame/",
      "filename": "reviewers-by-blame.jar",
      "version": "2.9-SNAPSHOT",
      "disabled": true
    }
  }
----

Substring(m)::
Limit the results to those plugins that match the specified substring.
+
The match is case insensitive. May not be used together with `r` or `p`.
+
List all plugins that match substring `project`:
+
.Request
----
  GET /plugins/?m=project HTTP/1.0
----
+
.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "delete-project": {
      "id": "delete-project",
      "index_url": "plugins/delete-project/",
      "filename": "delete-project.jar",
      "version": "2.9-SNAPSHOT"
    }
  }
----

[[install-plugin]]
=== Install Plugin
--
'PUT /plugins/link:#plugin-id[\{plugin-id\}].jar'
--

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.jar 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 --user admin:TNNuLkWsIV8w -X PUT -H "Content-Type:application/octet-stream" --data-binary @delete-project.jar 'http://gerrit:8080/a/plugins/delete-project.jar'
----

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
  Content-Length: 150

  )]}'
  {
    "id": "delete-project",
    "version": "v2.16-221-g35bb8bbac4",
    "index_url": "plugins/delete-project/",
    "filename": "delete-project.jar"
  }
----

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

  )]}'
  {
    "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

  )]}'
  {
    "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

  )]}'
  {
    "id": "delete-project",
    "version": "2.8",
    "disabled": true
  }
----

Disabling of a link:config-gerrit.html#plugins.mandatory[mandatory plugin]
is rejected:

.Request
----
  DELETE /plugins/replication HTTP/1.0
----

.Response
----
  HTTP/1.1 405 Method Not Allowed
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  Plugin replication is mandatory
----

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

  )]}'
  {
    "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",cols="1,^2,4"]
|=======================
|Field Name   ||Description
|`id`         ||The ID of the plugin.
|`version`    ||The version of the plugin.
|`api_version`|optional|The version of the Gerrit Api used by the plugin.
|`index_url`  |optional|URL of the plugin's default page.
|`filename`   |optional|The plugin's filename.
|`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",cols="1,6"]
|======================
|Field Name|Description
|`url`     |URL to the plugin jar.
|======================


GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------