= Plugin Site API
This the backend API for Jenkins Plugin Site frontend. It provides a REST API
to allow searching for plugins and retrieving specific plugin information.
== Architecture
The REST API calls are powered by Jersey 2.x running inside of Tomcat 8. Plugins
are stored and search via embedded Elasticsearch.
Plugin information sources include:
* Jenkins Update Center
** Main source of plugin data
* Jenkins Stats
** Installation statistics
* Jenkins Wiki
** Scrape wiki content
Elasticsearch mappings and data are initialized at runtime using a temporary
directory that is cleaned up at shutdown. The data is generated via separate
process and is currently stored in src/main/resources but in the future
will likely be available in the cloud so that it can be updated independently
of the application.
== Run Local Plugin Site API
----
DATA_FILE_URL="http://url.to/plugins.json.gzip" mvn jetty:run
----
This will launch an embedded Jetty container accessible at `http://localhost:8080`.
== Run Docker Plugin Site API
----
docker build -t jenkinsciinfra/plugin-site-api .
docker run -p 8080:8080 -it -e DATA_FILE_URL="http://url.to/plugins.json.gzip" jenkinsciinfra/plugin-site-api
----
== Rebuild Elasticsearch data
----
mvn -P generatePluginData
----
This will generate a new file in `target/plugins.json.gzip` consisting of plugin information and installation
statistics. This file should be uploaded to DATA_FILE_URL.
== REST API Reference
WARNING: This API is still in flux as the frontend and backend are
still being developed. As such this API is likely to change in the near future.
Unless otherwise indicated, all API calls:
* Produce JSON
* Do not require authentication
* Have no parameters or request body
Possible error codes for all calls:
* 500
=== GET /categories
Retrieve categories with their labels. It will be necessary to call /labels
to get the titles
Sample Response
----
{
"categories":
[
{
"id": "languagesPlatforms",
"title": "Platforms",
"description": "Jenkins plugins that are designed to give added support for building, testing or deploying to specific languages or platforms.",
"labels":
[
"ios", "dotnet", "android", "ruby", "scala"
]
},
...
],
"total": 6
}
----
=== GET /maintainers
Retrieve unique maintainers in the plugin data.
Sample Response
----
{
"maintainers": [
"Kohsuke Kawaguchi",
"Jesse Farinacci",
"Stephen Connolly",
"Gregory Boissinot",
"Oliver Gondža",
"Oleg Nenashev",
"Seiji Sogabe",
"Lucie Votypkova",
"Vojtech Juranek",
"Nicolas De Loof",
"Bap",
"Praqma Josra",
"Robert Sandell",
"Stefan Brausch",
.....
],
"limit": 909
}
----
=== GET /labels
Retrieve available plugin labels. "title" is an optional field so it may be
missing from some labels.
Sample Response
----
{
"labels" :
[
{
"id": "ios",
"title": "iOS development"
},
{
"id": "dotnet",
"title": "Azure and .NET"
},
{
"id": "android",
"title": "Android development"
},
{
"id": "ruby",
"title": "Ruby development"
},
{
"id": "scala",
"title": "Scala plugins"
},
....
],
"limit": 30
}
----
=== GET /plugin/:name
Retrieves information about a plugin
Could return 404 if plugin is not found
Sample Response
----
{
"buildDate": "Jul 04, 2016",
"categories": [
"scm"
],
"dependencies": [
{
"name": "matrix-project",
"optional": false,
"version": "1.6"
},
...
],
"maintainers": [
{
"id": "kohsuke",
"name": "Kohsuke Kawaguchi",
"email": null
},
...
],
"excerpt": "This plugin allows use of <a href='http://git-scm.com/'>Git</a> as a build SCM, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the [JENKINS:Git Client Plugin], which is only tested on official <a href='http://git-scm.com/'>git client</a>. Use exotic installations at your own risk.",
"gav": "org.jenkins-ci.plugins:git:2.5.2",
"labels": [
"scm"
],
"name": "git",
"previousTimestamp": "2016-07-02T20:46:28.00Z",
"previousVersion": "2.5.1",
"releaseTimetamp": null,
"requiredCore": "1.609.3",
"scm": "github.com",
"sha1": "0LNQKJ+Tcn9vTwqMbtxSi1SM+s0=",
"stats": {
"installations": [
{
"timestamp": 1322697600000,
"total": 8906
},
...
],
"installationsPercentage": [
{
"timestamp": 1459468800000,
"percentage": 61.16896694248365
},
...
],
"installationsPerVersion": [
{
"version": "2.0.3",
"total": 141
},
...
],
"installationsPercentagePerVersion": [
{
"version": "2.2.7",
"percentage": 0
},
...
],
"currentInstalls": 89232,
"trend": 2990
},
"title": "Jenkins Git plugin",
"url": "http://updates.jenkins-ci.org/download/plugins/git/2.5.2/git.hpi",
"version": "2.5.2",
"wiki": {
"content": <HTML content>,
"url": "https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin"
}
----
=== GET /plugins
Search for plugins
.Parameters
[options="header,footer"]
|=======================
|Name|Required|Description|Default Value|Possible Values|Example
|q|false|Search plugin name, title, excerpt if given|||workflow
|sort|false|Define how results are sorted|name|name,updated|name
|categories|false|Filter by categories|||scm
|labels|false|Filter by labels|||scm,ios
|maintainers|false|Filter by maintainers|||kohsuke
|core|false|Filter by required core version|||2.13
|limit|false|Specify page limit for results|50||25
|page|false|Specify page number to return. This is not zero based|1||3
|=======================
Sample Request
----
GET /plugins?q=git&sort=name&limit=3&page=1
----
Sample Response
----
{
"page": 1,
"pages": 3,
"plugins":
[
{
"buildDate": "Jul 04, 2016",
"categories": [
"scm"
],
"dependencies": [
{
"name": "matrix-project",
"optional": false,
"version": "1.6"
},
...
],
"maintainers": [
{
"id": "kohsuke",
"name": "Kohsuke Kawaguchi",
"email": null
},
...
],
"excerpt": "This plugin allows use of <a href='http://git-scm.com/'>Git</a> as a build SCM, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the [JENKINS:Git Client Plugin], which is only tested on official <a href='http://git-scm.com/'>git client</a>. Use exotic installations at your own risk.",
"gav": "org.jenkins-ci.plugins:git:2.5.2",
"labels": [
"scm"
],
"name": "git",
"previousTimestamp": "2016-07-02T20:46:28.00Z",
"previousVersion": "2.5.1",
"releaseTimetamp": null,
"requiredCore": "1.609.3",
"scm": "github.com",
"sha1": "0LNQKJ+Tcn9vTwqMbtxSi1SM+s0=",
"stats": {
"installations": [
{
"timestamp": 1322697600000,
"total": 8906
},
...
],
"installationsPercentage": [
{
"timestamp": 1459468800000,
"percentage": 61.16896694248365
},
...
],
"installationsPerVersion": [
{
"version": "2.0.3",
"total": 141
},
...
],
"installationsPercentagePerVersion": [
{
"version": "2.2.7",
"percentage": 0
},
...
],
"currentInstalls": 89232,
"trend": 2990
},
"title": "Jenkins Git plugin",
"url": "http://updates.jenkins-ci.org/download/plugins/git/2.5.2/git.hpi",
"version": "2.5.2",
"wiki": {
"url": "https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin"
}
},
...
],
"limit": 3,
"total": 7
}
----
=== GET /plugins/installed
Get top "limit" install plugins
.Parameters
[options="header,footer"]
|=======================
|Name|Required|Description|Default Value|Possible Values|Example
|limit|false|Specify limit for results|10||5
|=======================
Sample Request
----
GET /plugins/installed
----
Sample Response
----
{
"page": 1,
"pages": 3,
"plugins":
[
{
"buildDate": "Jul 04, 2016",
"categories": [
"scm"
],
"dependencies": [
{
"name": "matrix-project",
"optional": false,
"version": "1.6"
},
...
],
"maintainers": [
{
"id": "kohsuke",
"name": "Kohsuke Kawaguchi",
"email": null
},
...
],
"excerpt": "This plugin allows use of <a href='http://git-scm.com/'>Git</a> as a build SCM, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the [JENKINS:Git Client Plugin], which is only tested on official <a href='http://git-scm.com/'>git client</a>. Use exotic installations at your own risk.",
"gav": "org.jenkins-ci.plugins:git:2.5.2",
"labels": [
"scm"
],
"name": "git",
"previousTimestamp": "2016-07-02T20:46:28.00Z",
"previousVersion": "2.5.1",
"releaseTimetamp": null,
"requiredCore": "1.609.3",
"scm": "github.com",
"sha1": "0LNQKJ+Tcn9vTwqMbtxSi1SM+s0=",
"stats": {
"installations": [
{
"timestamp": 1322697600000,
"total": 8906
},
...
],
"installationsPercentage": [
{
"timestamp": 1459468800000,
"percentage": 61.16896694248365
},
...
],
"installationsPerVersion": [
{
"version": "2.0.3",
"total": 141
},
...
],
"installationsPercentagePerVersion": [
{
"version": "2.2.7",
"percentage": 0
},
...
],
"currentInstalls": 89232,
"trend": 2990
},
"title": "Jenkins Git plugin",
"url": "http://updates.jenkins-ci.org/download/plugins/git/2.5.2/git.hpi",
"version": "2.5.2",
"wiki": {
"url": "https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin"
}
},
...
],
"limit": 3,
"total": 7
}
----
=== GET /plugins/trend
Get top "limit" trending plugins
.Parameters
[options="header,footer"]
|=======================
|Name|Required|Description|Default Value|Possible Values|Example
|limit|false|Specify limit for results|10||5
|=======================
Sample Request
----
GET /plugins/trend
----
Sample Response
----
{
"page": 1,
"pages": 3,
"plugins":
[
{
"buildDate": "Jul 04, 2016",
"categories": [
"scm"
],
"dependencies": [
{
"name": "matrix-project",
"optional": false,
"version": "1.6"
},
...
],
"maintainers": [
{
"id": "kohsuke",
"name": "Kohsuke Kawaguchi",
"email": null
},
...
],
"excerpt": "This plugin allows use of <a href='http://git-scm.com/'>Git</a> as a build SCM, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the [JENKINS:Git Client Plugin], which is only tested on official <a href='http://git-scm.com/'>git client</a>. Use exotic installations at your own risk.",
"gav": "org.jenkins-ci.plugins:git:2.5.2",
"labels": [
"scm"
],
"name": "git",
"previousTimestamp": "2016-07-02T20:46:28.00Z",
"previousVersion": "2.5.1",
"releaseTimetamp": null,
"requiredCore": "1.609.3",
"scm": "github.com",
"sha1": "0LNQKJ+Tcn9vTwqMbtxSi1SM+s0=",
"stats": {
"installations": [
{
"timestamp": 1322697600000,
"total": 8906
},
...
],
"installationsPercentage": [
{
"timestamp": 1459468800000,
"percentage": 61.16896694248365
},
...
],
"installationsPerVersion": [
{
"version": "2.0.3",
"total": 141
},
...
],
"installationsPercentagePerVersion": [
{
"version": "2.2.7",
"percentage": 0
},
...
],
"currentInstalls": 89232,
"trend": 2990
},
"title": "Jenkins Git plugin",
"url": "http://updates.jenkins-ci.org/download/plugins/git/2.5.2/git.hpi",
"version": "2.5.2",
"wiki": {
"url": "https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin"
}
},
...
],
"limit": 3,
"total": 7
}
----
=== GET /plugins/updated
Get top "limit" recently updated plugins
.Parameters
[options="header,footer"]
|=======================
|Name|Required|Description|Default Value|Possible Values|Example
|limit|false|Specify limit for results|10||5
|=======================
Sample Request
----
GET /plugins/updated
----
Sample Response
----
{
"page": 1,
"pages": 3,
"plugins":
[
{
"buildDate": "Jul 04, 2016",
"categories": [
"scm"
],
"dependencies": [
{
"name": "matrix-project",
"optional": false,
"version": "1.6"
},
...
],
"maintainers": [
{
"id": "kohsuke",
"name": "Kohsuke Kawaguchi",
"email": null
},
...
],
"excerpt": "This plugin allows use of <a href='http://git-scm.com/'>Git</a> as a build SCM, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the [JENKINS:Git Client Plugin], which is only tested on official <a href='http://git-scm.com/'>git client</a>. Use exotic installations at your own risk.",
"gav": "org.jenkins-ci.plugins:git:2.5.2",
"labels": [
"scm"
],
"name": "git",
"previousTimestamp": "2016-07-02T20:46:28.00Z",
"previousVersion": "2.5.1",
"releaseTimetamp": null,
"requiredCore": "1.609.3",
"scm": "github.com",
"sha1": "0LNQKJ+Tcn9vTwqMbtxSi1SM+s0=",
"stats": {
"installations": [
{
"timestamp": 1322697600000,
"total": 8906
},
...
],
"installationsPercentage": [
{
"timestamp": 1459468800000,
"percentage": 61.16896694248365
},
...
],
"installationsPerVersion": [
{
"version": "2.0.3",
"total": 141
},
...
],
"installationsPercentagePerVersion": [
{
"version": "2.2.7",
"percentage": 0
},
...
],
"currentInstalls": 89232,
"trend": 2990
},
"title": "Jenkins Git plugin",
"url": "http://updates.jenkins-ci.org/download/plugins/git/2.5.2/git.hpi",
"version": "2.5.2",
"wiki": {
"url": "https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin"
}
},
...
],
"limit": 3,
"total": 7
}
----
=== GET /versions
Retrieve unique required Jenkins versions in the plugin data.
Sample Response
----
{
"limit": 226,
"versions": [
"1.580.1",
"1.625.3",
"1.424",
"1.609.3",
"1.609.1",
"1.398",
"1.466",
"1.480",
"1.596.1",
"1.532.3",
"1.580",
"1.509.4",
"1.642.3",
"1.580.3",
"1.447",
"1.532",
"1.609",
"1.509",
"1.554.1",
"1.480.3",
"1.509.3",
"1.392",
.....
]
}
----