Nutzung der MarketPlace API

Dieser Artikel soll die API vorstellen, mit der du die Veröffentlichung von Add-ons für BlueMind und deren Versionen auf dem MarketPlace automatisieren kannst.

Diese API kann auch auf dem MarketPlace BlueMind heruntergeladen werden.

API-Schlüssel

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

Meine Plugins und ihre Versionen

Um zu erfahren, welche Plugins veröffentlicht wurden, ob sie veröffentlicht sind oder nicht, welche ihre aktuelle Version ist und viele weitere Informationen, müssen Sie eine GET-Anfrage an die URL senden: https://marketplace.blue-mind.net/addons/api/plugins/. Diese Abfrage gibt die Informationen im JSON-Format zurück. Der API-Schlüssel, der mit dem Benutzerantrag verbunden ist, muss als Header der Anfrage in der Form enthalten sein: "api-key: la_cle_d_api".

Hier ist ein Beispiel für einen Python-Code, der diese Abfrage ermöglicht:

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

Vergessen Sie nicht, den API-Schlüssel durch den Schlüssel zu ersetzen, der mit Ihrem Konto auf dem MarketPlace verbunden ist.

Beispiele für die Implementierung in anderen Sprachen finden Sie am Ende dieser Seite. Wenn Sie die Abfrage in einer Sprache erstellen möchten, die nicht in der Abfrage enthalten ist, können Sie ein Beispiel für einen erzeugten Rahmen 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 spezielles Plugin

Um Informationen zu einem spezifischen Plugin zu erhalten (dessen ID bekannt ist), können Sie eine GET-Anfrage an die URL stellen: https://marketplace.blue-mind.net/addons/api/plugin/{id}/, wobei {id} die ID des betreffenden Plugins ist. Diese Anfrage wird Informationen über das gewünschte Plugin im JSON-Format zurückgeben, wenn der Nutzer Eigentümer dieses Plugins ist, andernfalls wird sie einen Fehler 403 zurückgeben. Für diese Anfrage müssen Sie auch den API-Schlüssel als Header der Anfrage in der Form inkludieren: "api-key: la_cle_d_api".

Hier ist ein Beispiel für einen Python-Code, der diese Abfrage ermöglicht:

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 Abfrage in einer Sprache erstellen möchten, die nicht in der Abfrage enthalten ist, können Sie ein Beispiel für einen erzeugten Rahmen 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

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 senden https://marketplace.blue-mind.net/addons/api/plugins/. Diese Informationen sind :

Name des Schlüssels	Obligatorisch	Beschreibung des Schlüssels
api_key	ja	Benutzerkennung des Nutzers, 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	Lange Beschreibung des zu erstellenden Plugins (wird unter den Screenshots angezeigt)
Lizenz	ja	Lizenz zur Veröffentlichung des zu erstellenden Plugins
installation_instructions	ja	Schritte zur Installation des Plugins
home_url	nicht	URL der mit dem Plugin verbundenen Website

Achtung

Da die Anfrage vom Typ "multipart/form-data" ist, wurde entschieden, dass die JSON-Daten mit dem Namen "json" verknüpft werden sollen. Wenn Sie sich nicht an diese Vereinbarung halten, wird der Antrag nicht erfolgreich sein.

Sie können auch Bilder hinzufügen, die mit dem Plugin verknüpft sind, indem Sie sie als verknüpfte Dateien an die POST-Anfrage anhängen. Die Namen der Bilder müssen der folgenden Konvention entsprechen:

Name	Beschreibung
thumbnail	Das Bild, das mit dem Logo des Plugins verknüpft ist.
*	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 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 Abfrage in einer Sprache erstellen möchten, die nicht in der Abfrage enthalten ist, können Sie ein Beispiel für einen erzeugten Rahmen 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--

Hinzufügen einer Plugin-Version

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

Name des Schlüssels	Obligatorisch	Beschreibung des Schlüssels
api_key	ja	Benutzerkennung des Nutzers, der das Plugin erstellen wird.
plugin_name	ja	Name des Plugins, das mit der Version verknüpft 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 über den Grund für diese neue Version

Achtung

Da die Anfrage vom Typ "multipart/form-data" ist, wurde entschieden, dass die JSON-Daten mit dem Namen "json" verknüpft werden sollen. Wenn Sie sich nicht an diese Vereinbarung halten, wird der Antrag nicht erfolgreich sein.

Achtung

Sie müssen dieser neuen Version eine Datei zuweisen (die herunterzuladende Datei), indem Sie sie der POST-Anfrage unter dem Namen "package" anhängen.

Hier ist ein Beispiel für einen Python-Code, der die Version 0.2 für das Plugin "Super Plugin" hinzufügt:

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 und wenn das Plugin nicht Ihr Eigentum ist (außer für einen Administrator des MarketPlace).

Beispiele für die Implementierung in anderen Sprachen finden Sie am Ende dieser Seite. Wenn Sie die Abfrage in einer Sprache erstellen möchten, die nicht in der Abfrage enthalten ist, können Sie ein Beispiel für einen erzeugten Rahmen 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 Sprachen

In Python

Hier ist ein vollständiges Skript, das die vorherigen Skripte aufgreift und POST oder GET (je nachdem, was kommentiert wird) auf dem MarketPlace ermöglicht:

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 Codeauszüge geben einen Einblick, was in Java getan werden muss, um funktionierende GET- und POST-Anfragen zu haben. Sie verwenden die APIs Apache HTTP und JSON-Simple.

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