c3afed6878
By adding Api version to PluginInfo, it becomes easier to check if all plugins of a Gerrit server got built for the correct Api. This is especially useful when upgrading servers. This commit only exposes the Api version through the Api. Showing it in the default output of the corresponding Ssh list command or in the UI will happen in follow-up commits. Change-Id: Id0c459dd104b4582fde1846e7710d6ad0ffc2f93
467 lines
9.6 KiB
Plaintext
467 lines
9.6 KiB
Plaintext
= 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
|
|
}
|
|
----
|
|
|
|
[[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
|
|
---------
|