REST API Documentation

Plugins registered on the instance, served from /new_api/plugins.

1. List registered plugins on the server

A plugin is an external javascript file, downloaded by the browser from a registered url. It is identified by its id, which stays the same when the plugin is updated, and the md5 hash of its code, which changes with every new version of the file. This lists the plugins marked as public, together with the projects in which each of them is available or loaded by default. When hash is given, the plugin with that hash is returned also when it is not public, which allows finding a plugin by its code.

Note	The result is paged - use the `page` and `size` query parameters to walk through it.

1.1. HTTP request

GET /minerva/new_api/plugins/ HTTP/1.1

1.2. Query Parameters

Parameter Description

Parameter	Description
`page`	index of the page to fetch, counted from 0; 0 by default
`size`	number of entries on a page; 20 by default, 10000 at most
`hash`	return only plugins with this hash of the javascript file, public or not unless `isPublic` is given
`isPublic`	return only plugins with this public flag; `true` by default unless `hash` is given; `false` without `hash` is admin only

page

index of the page to fetch, counted from 0; 0 by default

size

number of entries on a page; 20 by default, 10000 at most

hash

return only plugins with this hash of the javascript file, public or not unless isPublic is given

isPublic

return only plugins with this public flag; true by default unless hash is given; false without hash is admin only

1.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/plugins/' -X GET

1.4. HTTP response

HTTP/1.1 200 OK

1.5. Response Fields

Path Type Description

Path	Type	Description
`content`	`Array`	list of plugins on the page
`content[].hash`	`String`	plugin hash (identifier)
`content[].name`	`String`	human readable name of the plugin
`content[].version`	`String`	version of the plugin
`content[].isPublic`	`Boolean`	is the plugin visible in the list of plugins
`content[].defaultInProject`	`Array`	list of project ids where the plugin is loaded by default
`content[].availableInProject`	`Array`	list of project ids where the plugin is available
`content[].urls`	`Array`	list of urls where plugin is accessible
`totalPages`	`Number`	total number of pages
`totalElements`	`Number`	total number of elements
`numberOfElements`	`Number`	number of elements on this page
`size`	`Number`	page size
`number`	`Number`	page number

content

Array

list of plugins on the page

content[].hash

String

plugin hash (identifier)

content[].name

String

human readable name of the plugin

content[].version

String

version of the plugin

content[].isPublic

Boolean

is the plugin visible in the list of plugins

content[].defaultInProject

Array

list of project ids where the plugin is loaded by default

content[].availableInProject

Array

list of project ids where the plugin is available

content[].urls

Array

list of urls where plugin is accessible

totalPages

Number

total number of pages

totalElements

Number

total number of elements

numberOfElements

Number

number of elements on this page

size

Number

page size

number

Number

page number

1.6. Sample Response

{
  "content" : [ {
    "id" : 3,
    "hash" : "b7a875a0536949d4d8a2f834dc54489e",
    "name" : "Philip",
    "version" : "5.4.3",
    "defaultInProject" : [ ],
    "availableInProject" : [ ],
    "urls" : [ ],
    "isPublic" : true
  } ],
  "totalPages" : 1,
  "totalElements" : 1,
  "numberOfElements" : 1,
  "size" : 20,
  "number" : 0
}

2. Add plugin

Stores a plugin under the hash of its javascript file; the server downloads the file from the given url and rejects the request when its md5 does not match the declared hash. If a plugin with that hash is already registered and is not public, the url is added to it instead of creating a new entry.

2.1. HTTP request

POST /minerva/new_api/plugins/ HTTP/1.1

2.2. Request Fields

Path Type Description

Path	Type	Description
`name`	`String`	human readable name of the plugin
`version`	`String`	version of the plugin
`url`	`String`	location of the javascript file
`isPublic`	`Boolean`	should the plugin be listed in the browser
`defaultInProject`	`Array`	list of project ids where the plugin is loaded by default
`availableInProject`	`Array`	list of project ids where the plugin is available
`hash`	`String`	hash of plugin javascript file

name

String

human readable name of the plugin

version

String

version of the plugin

url

String

location of the javascript file

isPublic

Boolean

should the plugin be listed in the browser

defaultInProject

Array

list of project ids where the plugin is loaded by default

availableInProject

Array

list of project ids where the plugin is available

hash

String

hash of plugin javascript file

2.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/plugins/' -X POST \
    -d '{"hash":"b7a875a0536949d4d8a2f834dc54489e","name":"Antony Collier","version":"7.6.7","isPublic":true,"defaultInProject":[],"availableInProject":[],"url":"https://minerva-dev.lcsb.uni.lu/plugins/starter-kit/plugin.js"}' \
    -H 'Content-Type: application/json'

2.4. HTTP response

HTTP/1.1 201 Created

2.5. Response Fields

Path Type Description

Path	Type	Description
`hash`	`String`	plugin hash (identifier)
`name`	`String`	human readable name of the plugin
`version`	`String`	version of the plugin
`isPublic`	`Boolean`	is the plugin visible in the list of plugins
`defaultInProject`	`Array`	list of project ids where the plugin is loaded by default
`availableInProject`	`Array`	list of project ids where the plugin is available
`urls`	`Array`	list of urls where plugin is accessible

hash

String

plugin hash (identifier)

name

String

human readable name of the plugin

version

String

version of the plugin

isPublic

Boolean

is the plugin visible in the list of plugins

defaultInProject

Array

list of project ids where the plugin is loaded by default

availableInProject

Array

list of project ids where the plugin is available

urls

Array

list of urls where plugin is accessible

2.6. Sample Response

{
  "id" : 1,
  "hash" : "b7a875a0536949d4d8a2f834dc54489e",
  "name" : "Antony Collier",
  "version" : "7.6.7",
  "defaultInProject" : [ ],
  "availableInProject" : [ "*" ],
  "urls" : [ "https://minerva-dev.lcsb.uni.lu/plugins/starter-kit/plugin.js" ],
  "isPublic" : false
}

3. Update plugin

Replaces the definition of an already registered plugin; all fields must be sent, and the ones that are not provided are reset to their default values. Changing the hash or the url makes the server download the javascript file again and rejects the request when its md5 does not match the declared hash.

Admin only. The updated plugin is returned.

Note	Supports optimistic locking via the `If-Match` header.

3.1. HTTP request

PUT /minerva/new_api/plugins/6 HTTP/1.1

3.2. Path Parameters

Table 1. /minerva/new_api/plugins/{pluginId}
Parameter	Description
`pluginId`	plugin id

3.3. Request Fields

Path Type Description

Path	Type	Description
`name`	`String`	human readable name of the plugin
`version`	`String`	version of the plugin
`url`	`String`	location of the javascript file
`isPublic`	`Boolean`	should the plugin be listed in the browser
`defaultInProject`	`Array`	list of project ids where the plugin is loaded by default
`availableInProject`	`Array`	list of project ids where the plugin is available
`hash`	`String`	hash of plugin javascript file

name

String

human readable name of the plugin

version

String

version of the plugin

url

String

location of the javascript file

isPublic

Boolean

should the plugin be listed in the browser

defaultInProject

Array

list of project ids where the plugin is loaded by default

availableInProject

Array

list of project ids where the plugin is available

hash

String

hash of plugin javascript file

3.4. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/plugins/6' -X PUT \
    -d '{"hash":"b7a875a0536949d4d8a2f834dc54489e","name":"Rory Hayes","version":"1.3.3","isPublic":true,"defaultInProject":["Nova Feeney Sr."],"availableInProject":["Mrs. Sheri Oberbrunner"],"url":"https://minerva-dev.lcsb.uni.lu/plugins/starter-kit/plugin.js"}' \
    --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" \
    -H 'Content-Type: application/json'

3.5. HTTP response

HTTP/1.1 200 OK

3.6. Response Fields

Path Type Description

Path	Type	Description
`hash`	`String`	plugin hash (identifier)
`name`	`String`	human readable name of the plugin
`version`	`String`	version of the plugin
`isPublic`	`Boolean`	is the plugin visible in the list of plugins
`defaultInProject`	`Array`	list of project ids where the plugin is loaded by default
`availableInProject`	`Array`	list of project ids where the plugin is available
`urls`	`Array`	list of urls where plugin is accessible

hash

String

plugin hash (identifier)

name

String

human readable name of the plugin

version

String

version of the plugin

isPublic

Boolean

is the plugin visible in the list of plugins

defaultInProject

Array

list of project ids where the plugin is loaded by default

availableInProject

Array

list of project ids where the plugin is available

urls

Array

list of urls where plugin is accessible

3.7. Sample Response

{
  "id" : 6,
  "hash" : "b7a875a0536949d4d8a2f834dc54489e",
  "name" : "Rory Hayes",
  "version" : "1.3.3",
  "defaultInProject" : [ "Nova Feeney Sr." ],
  "availableInProject" : [ "Mrs. Sheri Oberbrunner" ],
  "urls" : [ "https://minerva-dev.lcsb.uni.lu/plugins/starter-kit/plugin.js" ],
  "isPublic" : true
}

4. Delete plugin

Unregisters the plugin, together with all data entries stored by it; this is a hard delete and cannot be undone.

Admin only.

Note	Supports optimistic locking via the `If-Match` header.

4.1. HTTP request

DELETE /minerva/new_api/plugins/7 HTTP/1.1

4.2. Path Parameters

Table 2. /minerva/new_api/plugins/{pluginId}
Parameter	Description
`pluginId`	plugin id

4.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/plugins/7' -X DELETE \
    --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx"

4.4. HTTP response

HTTP/1.1 200 OK

5. Access information about plugin

Retrieves a single plugin by its id, including all urls it can be downloaded from and the projects it is enabled in. Works also for plugins that are not public and therefore not returned by the listing.

5.1. HTTP request

GET /minerva/new_api/plugins/2 HTTP/1.1

5.2. Path Parameters

Table 3. /minerva/new_api/plugins/{pluginId}
Parameter	Description
`pluginId`	plugin id

5.3. CURL sample

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/plugins/2' -X GET

5.4. HTTP response

HTTP/1.1 200 OK

5.5. Response Fields

Path Type Description

Path	Type	Description
`hash`	`String`	plugin hash (identifier)
`name`	`String`	human readable name of the plugin
`version`	`String`	version of the plugin
`isPublic`	`Boolean`	is the plugin visible in the list of plugins
`defaultInProject`	`Array`	list of project ids where the plugin is loaded by default
`availableInProject`	`Array`	list of project ids where the plugin is available
`urls`	`Array`	list of urls where plugin is accessible

hash

String

plugin hash (identifier)

name

String

human readable name of the plugin

version

String

version of the plugin

isPublic

Boolean

is the plugin visible in the list of plugins

defaultInProject

Array

list of project ids where the plugin is loaded by default

availableInProject

Array

list of project ids where the plugin is available

urls

Array

list of urls where plugin is accessible

5.6. Sample Response

{
  "id" : 2,
  "hash" : "b7a875a0536949d4d8a2f834dc54489e",
  "name" : "Noel",
  "version" : "1.8.1",
  "defaultInProject" : [ "*" ],
  "availableInProject" : [ ],
  "urls" : [ ],
  "isPublic" : false
}

REST API Documentation - Plugin

1. List registered plugins on the server

1.1. HTTP request

1.2. Query Parameters

1.3. CURL sample

1.4. HTTP response

1.5. Response Fields

1.6. Sample Response

2. Add plugin

2.1. HTTP request

2.2. Request Fields

2.3. CURL sample

2.4. HTTP response

2.5. Response Fields

2.6. Sample Response

3. Update plugin

3.1. HTTP request

3.2. Path Parameters

3.3. Request Fields

3.4. CURL sample

3.5. HTTP response

3.6. Response Fields

3.7. Sample Response

4. Delete plugin

4.1. HTTP request

4.2. Path Parameters

4.3. CURL sample

4.4. HTTP response

5. Access information about plugin

5.1. HTTP request

5.2. Path Parameters

5.3. CURL sample

5.4. HTTP response

5.5. Response Fields

5.6. Sample Response