Veröffentlichung über die Marketplace-API

Dieser Artikel soll die API vorstellen, mit der sich die Veröffentlichung von Add-ons für BlueMind und deren Versionen auf dem Marketplace automatisieren lässt.

Diese API kann selbst im BlueMind Marketplace heruntergeladen werden.

API-Schlüssel

Um die API zu verwenden, benötigen Sie Ihren API-Schlüssel, der im Administrationsbereich verfügbar ist: https://marketplace.blue-mind.net/admin/. Dieser API-Schlüssel kann nur vom Administrator der Website geändert werden.

Meine Plugins und deren Versionen

Um zu erfahren, welche Plugins Sie veröffentlicht haben, welchen Status sie haben (veröffentlicht oder nicht), welche aktuelle Version vorliegt und viele weitere Informationen zu erhalten, müssen Sie eine GET-Anfrage an die folgende URL senden: https://marketplace.blue-mind.net/addons/api/plugins/. Diese Anfrage liefert die Informationen im JSON-Format zurück. Der API-Schlüssel des anfragenden Benutzers muss als Header der Anfrage in der Form „api-key: der_API-Schlüssel“ angegeben werden.

Hier ist ein Beispiel für Python-Code, mit dem Sie diese Anfrage stellen können:

GET /api/plugins/

import requests

headers = {
    'api-key': 'your_api_key'
}

URL = 'https://marketplace.blue-mind.net/addons/api/plugins/'

req = requests.get(URL, headers=headers, verify=False)
print "Status code : " + str(req.status_code)
if req.text:
    print "Contents : " + str(json.dumps(req.json(), indent=4, sort_keys=True))

Tipp

Bitte denken Sie daran, den API-Schlüssel durch den Schlüssel zu ersetzen, der Ihrem Konto im Marketplace zugeordnet ist.

Beispiele für die Implementierung in anderen Sprachen finden Sie am Ende dieser Seite. Wenn Sie die Anfrage in einer Sprache erstellen möchten, die dort nicht aufgeführt ist, können Sie ein Beispiel für ein generiertes Template entwickeln:

GET /addons/api/plugins/ HTTP/1.1

Host: marketplace.blue-mind.net

Content-Length: 51

Content-Type: application/x-www-form-urlencoded

Accept-Encoding: gzip, deflate

Accept: */*

User-Agent: python-requests/2.3.0 CPython/2.7.5+ Linux/3.11.0-12-generic

api-key: your_api_key

Ein bestimmtes Plugin

Um Informationen zu einem bestimmten Plugin (dessen ID bekannt ist) abzurufen, können Sie eine GET-Anfrage an die folgende URL senden: https://marketplace.blue-mind.net/addons/api/plugin/{id}/, wobei {id} die ID des betreffenden Plugins ist. Diese Anfrage liefert Informationen zum gewünschten Plugin im JSON-Format, sofern der Nutzer Eigentümer dieses Plugins ist; andernfalls wird ein 403-Fehler zurückgegeben. Bei dieser Anfrage muss außerdem der API-Schlüssel als Header der Anfrage in der Form „api-key: der_API-Schlüssel“ angegeben werden.

Hier ist ein Beispiel für Python-Code, mit dem Sie diese Anfrage stellen können:

GET /api/plugin/1

import requests

headers = {
    'api-key': 'your_api_key'
}

URL = 'https://marketplace.blue-mind.net/addons/api/plugin/1/'

req = requests.get(URL, headers=headers, verify=False)
print "Status code : " + str(req.status_code)
if req.text:
    print "Contents : " + str(json.dumps(req.json(), indent=4, sort_keys=True))

Beispiele für die Implementierung in anderen Sprachen finden Sie am Ende dieser Seite. Wenn Sie die Anfrage in einer Sprache erstellen möchten, die dort nicht aufgeführt ist, können Sie ein Beispiel für ein generiertes Template entwickeln:

GET /addons/api/plugin/1/ HTTP/1.1

Host: [marketplace.blue-mind.net](http://marketplace.blue-mind.net)

Content-Length: 51

Content-Type: application/x-www-form-urlencoded

Accept-Encoding: gzip, deflate

Accept: */*

User-Agent: python-requests/2.3.0 CPython/2.7.5+ Linux/3.11.0-12-generic

api-key: your_api_key

Ein Plugin hinzufügen

Um ein Plugin hinzuzufügen, müssen Sie eine POST-Anfrage erstellen, die die Informationen für dessen Erstellung im JSON-Format enthält, und diese Anfrage an die URL https://marketplace.blue-mind.net/addons/api/plugins/ senden. Diese Informationen sind:

Schlüsselname	Erforderlich	Beschreibung des Schlüssels
api_key	ja	Benutzername des Benutzers, der ein Plugin erstellen wird
name	ja	Name des zu erstellenden Plugins
shortdesc	ja	Kurzbeschreibung des zu erstellenden Plugins (wird unter dem Titel angezeigt)
Beschreibung	ja	Ausführliche Beschreibung des zu erstellenden Plugins (wird unter den Screenshots angezeigt)
Lizenz	ja	Lizenz für die Veröffentlichung des zu erstellenden Plugins
installation_instructions	ja	Vorgehensweise zur Installation des Plugins
home_url	nein	URL der mit dem Plugin verknüpften Website

Achtung

Da es sich bei der Anfrage um den Typ „multipart/form-data“ handelt, wurde festgelegt, dass die JSON-Daten den Namen „JSON“ tragen müssen. Wenn Sie diese Konvention nicht einhalten, wird die Anfrage fehlschlagen.

Sie können außerdem Bilder zum Plugin hinzufügen, indem Sie diese als angehängte Dateien in der POST-Anfrage übermitteln. Die Namen der Bilder müssen der folgenden Konvention entsprechen:

Name	Beschreibung
thumbnail	Das dem Plugin-Logo zugeordnete Bild.
*	Jedes Bild mit einem anderen Namen wird als Screenshot für das Plugin importiert.

Tipp

Die Anzahl der Screenshots ist nicht begrenzt.

Hier ist ein Beispielcode in Python, der ein Plugin mit einem Logo und zwei Bildschirmfotos (Screenshots) erstellt:

POST /api/plugins/

import requests, json

data = {
  'api_key': 'your_api_key',
  'name': 'Super plugin',
  'shortdesc': 'A short description',
  'description': 'A long description',
  'license': 'A license',
  'installation_instructions': 'Some instructions',
  'home_url': "http://www.blue-mind.net"
}

files = {
    'thumbnail': open('/home/user/Images/my_thumbnail.jpg', 'rb'),
    'screen1': open('/home/user/Images/my_screenshot1.png', 'rb'),
    'screen2': open('/home/user/Images/my_screenshot2.png', 'rb')
}

URL = 'https://marketplace.blue-mind.net/addons/api/plugins/'

req = requests.post(URL, files=files, data={'json': json.dumps(data)}, verify=False)
print "Status code : " + str(req.status_code)

Beispiele für die Implementierung in anderen Sprachen finden Sie am Ende dieser Seite. Wenn Sie die Anfrage in einer Sprache erstellen möchten, die dort nicht aufgeführt ist, können Sie ein Beispiel für ein generiertes Template entwickeln:

POST /addons/api/plugins/ HTTP/1.1
Host: [marketplace.blue-mind.net](http://marketplace.blue-mind.net)
Content-Length: 279271
Content-Type: multipart/form-data; boundary=1824dd5f14f14e57bb2b2a27424628db
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.3.0 CPython/2.7.5+ Linux/3.11.0-12-generic

--1824dd5f14f14e57bb2b2a27424628db
Content-Disposition: form-data; name="json"
{"home_url": "[http://www.blue-mind.net](http://www.blue-mind.net)", "name": "Super plugin", "license": "A license", "installation_instructions": "Some instructions", "shortdesc": "A short description", "api_key": "your_api_key", "description": "A long description"}


--1824dd5f14f14e57bb2b2a27424628db
Content-Disposition: form-data; name="screen2"; filename="my_screenshot2.png"
[... DATA ...]
--1824dd5f14f14e57bb2b2a27424628db--
--1824dd5f14f14e57bb2b2a27424628db
Content-Disposition: form-data; name="screen1"; filename="my_screenshot1.png"
[... DATA ...]
--1824dd5f14f14e57bb2b2a27424628db--
--1824dd5f14f14e57bb2b2a27424628db
Content-Disposition: form-data; name="thumbnail"; filename="my_thumbnail.jpg"
[... DATA ...]
--1824dd5f14f14e57bb2b2a27424628db--

Eine Plugin-Version hinzufügen

Um eine Plugin-Version zu einem Plugin hinzuzufügen, das Ihnen gehört, müssen Sie eine POST-Anfrage erstellen, die die Informationen zur Erstellung der Version im JSON-Format enthält, und diese Anfrage an die folgende URL senden: https://marketplace.blue-mind.net/addons/api/plugin_version/. Diese Informationen sind:

Schlüsselname	Erforderlich	Beschreibung des Schlüssels
api_key	ja	Benutzername des Benutzers, der das Plugin erstellen wird
plugin_name	ja	Name des Plugins, das der Version zugeordnet ist
version	ja	Nummer der neuen Version des Plugins
target_bm_versions	ja	BlueMind-Versionen, die von dieser neuen Version betroffen sind
release_notes	ja	Informationen zum Grund für diese neue Version

Achtung

Da es sich bei der Anfrage um den Typ „multipart/form-data“ handelt, wurde festgelegt, dass die JSON-Daten den Namen „JSON“ tragen müssen. Wenn Sie diese Konvention nicht einhalten, wird die Anfrage fehlschlagen.

Achtung

Sie müssen dieser neuen Version eine Datei zuordnen (die herunterzuladende Datei), indem Sie sie der POST-Anfrage unter dem Namen „package“ beifügen.

Hier ist ein Beispiel für Python-Code, mit dem Sie die Version 0.2 für das Plugin „Super Plugin“ hinzufügen können:

POST /api/plugin_version/

import requests, json

data = {
  'api_key': 'your_api_key',
  'plugin_name': 'Super plugin',
  'version': '0.2',
  'target_bm_versions': '3.x',
  'release_notes': 'Brand new release'
}

files = {
    'package': open('/home/user/Files/super_plugin.jar', 'rb')
}

URL = 'https://marketplace.blue-mind.net/addons/api/plugin_version/'

req = requests.post(URL, files=files, data={'json': json.dumps(data)}, verify=False)
print "Status code : " + str(req.status_code)

Achtung

Die neue Version wird abgelehnt, wenn sie keine Datei enthält oder wenn das Add-on nicht Ihnen gehört (außer für einen Marketplace-Administrator).

Beispiele für die Implementierung in anderen Sprachen finden Sie am Ende dieser Seite. Wenn Sie die Anfrage in einer Sprache erstellen möchten, die dort nicht aufgeführt ist, können Sie ein Beispiel für ein generiertes Template entwickeln:

POST /addons/api/plugin_version/ HTTP/1.1

Host: [marketplace.blue-mind.net](http://marketplace.blue-mind.net)

Content-Length: 1191498

Content-Type: multipart/form-data; boundary=947a3f6396a244a99118fd5a3faa5204

Accept-Encoding: gzip, deflate

Accept: */*

User-Agent: python-requests/2.3.0 CPython/2.7.5+ Linux/3.11.0-12-generic

 

--947a3f6396a244a99118fd5a3faa5204

Content-Disposition: form-data; name="json"

{"api_key": "your_api_key", "release_notes": "Ceci est une nouvelle release", "version": "0.2", "plugin_name": "Super plugin", "target_bm_versions": "3.x"}

 

--947a3f6396a244a99118fd5a3faa5204

Content-Disposition: form-data; name="package"; filename="super_plugin.jar"

[... DATA ...]

--947a3f6396a244a99118fd5a3faa5204--

Verwendung der API in verschiedenen Programmiersprachen

In Python

Hier finden Sie ein vollständiges Skript, das die vorherigen Skripte zusammenfasst und es ermöglicht, POST- oder GET-Anfragen (je nachdem, was auskommentiert ist) an den Marketplace zu senden:

Vollständiges Skript

#!/usr/bin/env python
# -\*- coding: utf-8 -\*-
import requests, json

WEBSITE = "https://marketplace.blue-mind.net/"
API_KEY = "your_api_key"

#### POST PLUGIN
data = {
  'api_key': API_KEY,
  'name': 'Super plugin',
  'shortdesc': 'A short description',
  'description': 'A long description',
  'license': 'A license',
  'installation_instructions': 'Several instructions !',
  'home_url': "http://www.blue-mind.net"
}

files = {
    'thumbnail': open('/home/user/Images/thumbnail.jpg', 'rb'),
    'screen1': open('/home/user/Images/screenshot1.png', 'rb'),
    'screen2': open('/home/user/Images/screenshot1.png', 'rb')
}

URL = WEBSITE + 'addons/api/plugins/'

#### POST PLUGIN VERSION
# data = {
#   'api_key': API_KEY,
#   'plugin_name': 'Super plugin',
#   'version': '0.2',
#   'target_bm_versions': '3.x',
#   'release_notes': 'On vient de faire une nouvelle release'
# }
#
# files = {
#     'package': open('/home/user/Files/super_plugin.jar', 'rb')
# }
#
# URL = WEBSITE + 'addons/api/plugin_version/'

#### POST REQUEST
req = requests.post(URL, files=files, data={'json': json.dumps(data)}, verify=False)


#### GET PLUGINS
# headers = {
#     'api-key': API_KEY
# }
#
# URL = WEBSITE + 'addons/api/plugins/'
#
# #### GET REQUEST
# req = requests.get(URL, headers=headers, verify=False)


#### POST OR GET RESPONSE
print "Status code : " + str(req.status_code)
if req.text:
    print "Contents : " + str(json.dumps(req.json(), indent=4, sort_keys=True))

Laden Sie den Quellcode herunter:

api_python.py

In Java

Die folgenden Codeausschnitte geben einen Überblick darüber, was in Java erforderlich ist, um funktionierende GET- und POST-Anfragen zu erstellen. Dabei werden die Apache-HTTP- und JSON-Simple-APIs verwendet .

GET /addons/api/plugins

private static HttpClient httpClient = StaticTools.getHttpClient(true);
private static String API_KEY = "your_api_key";
private static String WEBSITE = "https://marketplace.blue-mind.net/";

private static void getPlugins() throws IOException {
    HttpGet httpGet = new HttpGet(WEBSITE + "/addons/api/plugins/");
    httpGet.addHeader("api-key", API_KEY);
    ResponseHandler<String> handler = new BasicResponseHandler();
    HttpResponse rep = httpClient.execute(httpGet);
    if (rep != null) {
        int statusCode = rep.getStatusLine().getStatusCode();
        System.out.println("Status code : " + statusCode);
        if (statusCode == 200) {
            System.out.println("Contents : " + handler.handleResponse(rep));
        }
    }
}

GET /addons/api/plugin/id

private static HttpClient httpClient = StaticTools.getHttpClient(true);
private static String API_KEY = "your_api_key";
private static String WEBSITE = "https://marketplace.blue-mind.net/";
    
private static void getPlugin(int id) throws IOException {
    HttpGet httpGet = new HttpGet(WEBSITE + "/addons/api/plugin/" + id);
    httpGet.addHeader("api-key", API_KEY);
    ResponseHandler<String> handler = new BasicResponseHandler();
    HttpResponse rep = httpClient.execute(httpGet);
    if (rep != null) {
        int statusCode = rep.getStatusLine().getStatusCode();
        System.out.println("Status code : " + statusCode);
        if (statusCode == 200) {
            System.out.println("Contents : " + handler.handleResponse(rep));
        }
    }
}

POST /addons/api/plugins

private static HttpClient httpClient = StaticTools.getHttpClient(true);
private static String API_KEY = "your_api_key";
private static String WEBSITE = "https://marketplace.blue-mind.net/";
    
@SuppressWarnings("unchecked")
private static void postPlugin() throws IOException {
    HttpPost httpPost = new HttpPost(WEBSITE + "/addons/api/plugins/");
    MultipartEntityBuilder builder = MultipartEntityBuilder.create();
    ContentType contentType = ContentType.getOrDefault(null);
    
    // Json part
    JSONObject j = new JSONObject();
    j.put("api_key", API_KEY);
    j.put("name", "Super plugin");
    j.put("shortdesc", "A short description");
    j.put("description", "A long description");
    j.put("license", "A license");
    j.put("installation_instructions", "Several instructions");
    j.put("home_url", "http://www.blue-mind.net");
    StringBody json = new StringBody(j.toString(), contentType);
     
    // Files part
    FileBody thumbnail = new FileBody(new File("/home/user/Images/thumbnail.jpg"));
    FileBody screen1 = new FileBody(new File("/home/user/Images/screenshot1.png"));
    FileBody screen2 = new FileBody(new File("/home/user/Images/screenshot2.png"));
    
    // Grouping
    builder.addPart("json", json);
    builder.addPart("thumbnail", thumbnail);
    builder.addPart("screen1", screen1);
    builder.addPart("screen2", screen2);
      
    httpPost.setEntity(builder.build());
    HttpResponse rep = httpClient.execute(httpPost);
    if (rep != null) {
        int statusCode = rep.getStatusLine().getStatusCode();
        System.out.println("Status code : " + statusCode);
    }
}

POST /addons/api/plugin_version

private static HttpClient httpClient = StaticTools.getHttpClient(true);
private static String API_KEY = "your_api_key";
private static String WEBSITE = "https://marketplace.blue-mind.net/";

@SuppressWarnings("unchecked")
private static void postPluginVersion() throws IOException {
    HttpPost httpPost = new HttpPost(WEBSITE + "/addons/api/plugin_version/");
    MultipartEntityBuilder builder = MultipartEntityBuilder.create();
    ContentType contentType = ContentType.getOrDefault(null);
    
    // Json part
    JSONObject j = new JSONObject();
    j.put("api_key", API_KEY);
    j.put("plugin_name", "Super plugin");
    j.put("version", "0.2");
    j.put("target_bm_versions", "3.x");
    j.put("release_notes", "On vient de faire une nouvelle release");
    StringBody json = new StringBody(j.toString(), contentType);
    
    // Files part
    FileBody pack = new FileBody(new File("/home/user/Files/super_plugin.jar"));
    
    // Grouping
    builder.addPart("json", json);
    builder.addPart("package", pack);
    
    httpPost.setEntity(builder.build());
    HttpResponse rep = httpClient.execute(httpPost);
    if (rep != null) {
        int statusCode = rep.getStatusLine().getStatusCode();
        System.out.println("Status code : " + statusCode);
    }
}

Laden Sie den Quellcode herunter:

api_java.zip