Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
AUF DIESER SEITE
 

RESTful API-Übersicht

Machen Sie sich mit Representational State Transfer (REST) vertraut und erfahren Sie, wie Sie RESTful-APIs mit Juniper Mist™ verwenden können.

Die 100%ige API-Architektur von Juniper Mist unterstützt jede sichtbare Funktion im Juniper Mist Portal. Alles, was Sie im Portal tun können, können Sie mithilfe der API in großem Umfang automatisieren. Representational State Transfer (REST) ist eine zustandslose Client/Server-Architektur mit einer einheitlichen Schnittstelle. Da Maschinen keine Verwendung für eine Benutzeroberfläche haben, ermöglichen APIs eine definierte und schnellere Art und Weise, wie Maschinen miteinander kommunizieren können.

Mit REST-APIs können Sie Ihre eigene Art der Interaktion mit Systemen und Anwendungen erstellen. Sie können sogar benutzerdefinierte Funktionen erstellen. Andere gängige Anwendungsszenarien für REST-APIs sind die Kommunikation und der Datenaustausch zwischen Anwendungen, der Datenaustausch zwischen Anwendungen und Servern, die Kommunikation zwischen Microservices innerhalb einer Anwendung und vieles mehr. REST ist zustandslos, was es ideal für Cloud-basierte Dienste macht.

Die Juniper Mist-API steht jedem Kunden mit einem Juniper Mist Konto zur Verfügung.

Weitere Informationen finden Sie auch in der Mist-API-Referenz. Dies enthält zusätzliche Dokumentation für Entwickler sowie die Möglichkeit, API-Aufrufe zu testen.

Juniper Mist API-Architektur

Juniper Mist verwendet REST-APIs, die HTTP-Methoden (GET, POST, PUT und DELETE) verwenden, um Daten im JSON-Format (JavaScript Object Notation) zu übertragen.

RESTful-API-Anfragen

Die Verwendung von RESTful-APIs folgt einer ähnlichen Praxis wie die CRUD-Methodik (Create, Read, Update, Delete), die bei der Entwicklung verwendet wird. Dies sind die vier grundlegenden Aktionen oder Funktionen, die bei der Arbeit mit Daten verwendet werden.

Tabelle 1: Grundlegende CRUD-Aktionen
CRUD HTTP/REST
Schaffen BEREITSTELLEN
Lesen ERHALTEN
Aktualisieren STELLEN
Löschen LÖSCHEN

URL-Format für API-Endpunkt

Die API-Endpunkt-URL besteht aus zwei Teilen:

  • API-Host (oder Endpunkt): Der Endpunkt für die globale Region, der Ihre Juniper Mist Organisation zugeordnet ist. Diese Endpunkte sind unter API-Endpunkte und globale Regionen aufgeführt.

  • Funktion: Alles, was auf dem API-Endpunkt folgt, stellt die Funktion dar, die die API aufruft.

Beispiel

https://{api-host}/api/v1/sites/{site_id}/stats/devices/{device_id}aus.

https://api.mist.com/api/v1/sites/13b0ee00-121a-456e-84e0-ead3008bc2f2/stats/devices/00000000-0000-0000-1000-d420b08532eb

Anmerkung:

Ersetzen Sie bei der Wiederverwendung von Codeblöcken Platzhalterwerte durch tatsächliche Werte, z. B. Ihr API-Token, Ihre Unternehmens-ID, Ihre Standort-ID, Ihren AP-Namen usw.

Alles, was nach {api-host} kommt, ist die Funktion. Der Anruf geht an die globale Cloud und fordert die Statistiken für das angegebene Gerät am angegebenen Standort an.

Im nächsten Abschnitt wird die Struktur, aus der ein API-Aufruf besteht, genauer betrachtet.

Struktur von API-Aufrufen

Die folgende Abbildung ist ein Beispiel für einen API-Aufruf und die verschiedenen Komponenten, aus denen er besteht.

Tabelle 2: API-Aufrufkomponenten

API-Aufrufkomponente

Beschreibung

HTTP-Methode

  • POST – Erstellt ein Objekt. – Mit POST werden alle vorhandenen Werte mit den in der Nutzlast enthaltenen Werten überschrieben. Werte, die nicht in der POST-Nutzlast angegeben sind, werden auf ihre ursprünglichen Werte zurückgesetzt.

  • GET – Objekte auflisten. – GET gibt den Wert einer Ressource oder einer Liste von Ressourcen zurück, je nachdem, ob ein Bezeichner angegeben ist.

    • GET /api/v1/orgs/:org_id

      Gibt Informationen über die Organisation basierend auf dem angegebenen :org_id zurück.

    • GET /api/v1/orgs/:org_id/site

      Gibt eine Liste von Websites zurück, die zu :org_id gehören.

    • GET /api/v1/sites/:site_id

      Gibt Informationen über den Standort zurück, der durch :site_id angegeben wird.

  • PUT – Aktualisiert ein Objekt. – Mit PUT werden alle angegebenen Werte in der Nutzlast geändert. Bei der Aktualisierung mit einem PUT behalten einfache Werte (Zeichenfolgen oder Zahlen), die nicht in der Nutzlast angegeben sind, ihre vorhandenen Werte bei. Wenn der Wert eine Datenstruktur enthält, z. B. ein Array oder ein Objekt, ersetzen die in der Nutzlast enthaltenen Werte diese Struktur in ihrer Gesamtheit. Behalten Sie dies im Hinterkopf, um unerwünschte Änderungen an vorhandenen Werten zu vermeiden.

  • DELETE (DELETE) – Entfernt ein Objekt. – Mit DELETE wird eine Ressource entfernt.

Host (oder API-Endpunkt)

Bestimmt die zu verwendende Juniper Mist Cloud (Global 01, EMEA 01 usw.). Der Endpunkt für die globale Region, der Ihre Juniper Mist Organisation zugeordnet ist. Weitere Informationen finden Sie unter API-Endpunkte und globale Regionen.

Version

Die zu verwendende API-Version (derzeit verwenden alle APIs v1).

Umfang

Gibt die Ebene an, auf der die Anforderung ausgeführt wird. Beispiele hierfür sind "msp", "org", "site", "self", "register", "installer", "const" usw.

Bereichs-ID

Identifiziert den zu verwendenden Bereich.

Objekt

Der Typ des zu verwendenden Objekts (Gerät, WLAN usw.).

Objekt-ID

Identifiziert das anzufordernde Objekt.

Um einen der oben genannten REST-Befehle (POST, GET, PUT, DELETE) für die REST-API ausführen zu können, müssen Sie in jeder Anforderung einige Anforderungen erfüllen, z. B.:

  • Authentifizierung:

    • Sie können ein API-Token, Juniper Mist Anmeldeinformationen oder einen externen OAuth2-Anbieter verwenden, um anzugeben, wer Sie sind und worauf Sie während des Authentifizierungsprozesses Zugriff haben.

    • Weitere Informationen zu den verschiedenen Authentifizierungsmethoden finden Sie unter Authentifizierung.

      Anmerkung:

      Wenn Sie bereits bei manage.mist.com angemeldet sind, können Sie einfach einen neuen Browser-Tab öffnen und auf https://api.mist.com/api/v1/self/apitokens gehen und auf die Schaltfläche POSTEN klicken. Dadurch wird automatisch ein neues API-Benutzertoken erstellt.

      Weitere Informationen zu Token finden Sie unter Erstellen von API-Token.

  • HTTP-Header: Dieser Header gibt den Inhalt und den Autorisierungstyp wie folgt an:

    • Für Juniper Mist ist der Inhaltstyp immer application/json.

    • Die Autorisierung kann ein Token oder ein Cookie (einschließlich CSRF-Token und Session-ID) sein.

  • Der Endpunkt für die globale Region, der Ihre Juniper Mist Organisation zugeordnet ist. Weitere Informationen finden Sie unter API-Endpunkte und globale Regionen.

  • JSON-Nutzdaten

Die folgende Tabelle enthält Beispiele für die verschiedenen Teile, aus denen eine RESTful-API-Anforderung besteht.

Tabelle 3: Beispiele für RESTful-API-Anfragen

CRUD-Betrieb

HTTP-Header-Authentifizierung

Endpunkt-URL

Nutzdaten (JSON)

ERHALTEN

API-Token

https://api.mist.com/api/v1/sites/:site_id/wlans

  

LÖSCHEN

CSRF-Token, Sitzungs-ID

https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id

  

BEREITSTELLEN

CSRF-Token, Sitzungs-ID

https://api.mist.com/api/v1/orgs/:org_id/inventory

{["<claim_code>"]}

STELLEN

API-Token

https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id

{"ssid" : "Neuer Name"}

JSON-Nutzdaten

Unterschiedliche Funktionen erfordern unterschiedliche Elemente in der JSON-Nutzlast. Die erforderlichen Details können Sie in der API-Dokumentation einsehen.

Im Folgenden finden Sie einen Beispiel-API-Aufruf und die Antwort (JSON-Nutzlast).

API-Aufruf:

Antwort (JSON-Nutzlast):

Begrenzung der API-Rate

Juniper Mist ist auf 5.000 API-Aufrufe pro Stunde beschränkt. Wenn Sie mehr als 5.000 Anrufe pro Stunde tätigen müssen, erstellen Sie ein Support-Ticket.

Bei großen Bereitstellungen wird empfohlen, API-Aufrufe auf Organisationsebene durchzuführen, um zu vermeiden, dass das API-Aufruflimit schnell erreicht wird.

Anmerkung:

Um Brute-Force-Angriffe zu verhindern, ist die Rate der Anmelde-API (/api/v1/login) nach drei fehlgeschlagenen Anmeldungen begrenzt.

API-Authentifizierungsoptionen

Die Juniper Mist-API bietet drei Optionen zum Anfordern der Authentifizierung:

  • Standardauthentifizierung – Token

  • HTTP-Anmeldung – Benutzername und Kennwort

    • Ist wie eine Dashboard-Anmeldung.

    • Kann eine Zwei-Faktor-Authentifizierung sein.

  • OAuth2

    • Das Konto muss mit einem OAuth-Anbieter verknüpft sein.

    • Erfordert Browserzugriff.

Weitere Informationen zur Authentifizierung finden Sie in der Mist API-Referenz.

Ein einfaches API-Beispiel

Die Django-API-Schnittstelle ist eine webbasierte Schnittstelle, auf der Sie CRUD-Vorgänge innerhalb der API ausführen können. Weitere Informationen finden Sie unter Verwenden der Django-Webschnittstelle zum Vornehmen von API-Änderungen.

Mit der Django-API-Schnittstelle können Sie Ihren ersten API-Aufruf tätigen. Nachdem Sie sich bei Mist angemeldet haben, öffnen Sie mit demselben Browser ein neues Fenster und geben Sie die URL https://api.mist.com/api/v1/selfein. Dies ist die URL für die Global 01 Cloud. Wenn Sie eine andere Cloud verwenden, lautet diese URL anders.

Dies entspricht dem Ausführen dieses API-Aufrufs GET /api/v1/self.

Das oben gezeigte Ergebnis zeigt die Berechtigungen an, die Ihnen für die Organisationen und Websites zugewiesen wurden, denen Sie zugeordnet sind.

Zugehörige Dokumentation