API-Grundlagen
Änderungen vorschlagen
PDFs
In der Web Services-API umfasst HTTP-Kommunikation einen Anforderungsantwort-Zyklus.
URL-Elemente in Anforderungen
Unabhängig von der verwendeten Programmiersprache oder dem verwendeten Werkzeug hat jeder Aufruf der Web Services-API eine ähnliche Struktur, mit einer URL, einem HTTP-Verb und einem Accept-Header.
Alle Anforderungen enthalten wie im folgenden Beispiel eine URL und enthalten die in der Tabelle beschriebenen Elemente.
https://webservices.name.com:8443/devmgr/v2/storage-systems
| Werden | Beschreibung |
|---|---|
HTTP-Übertragung
|
Der Web Services Proxy ermöglicht die Verwendung von HTTP oder HTTPS. Aus Sicherheitsgründen erfordert die integrierten Webdienste HTTPS. |
Basis-URL und Port
|
Jede Anforderung muss korrekt an eine aktive Instanz von Webservices weitergeleitet werden. Der FQDN (vollständig qualifizierter Domänenname) oder die IP-Adresse der Instanz sind zusammen mit dem Listening-Port erforderlich. Standardmäßig kommuniziert Web Services über Port 8080 (für HTTP) und Port 8443 (für HTTPS). Für den Web Services Proxy können beide Ports während der Proxy-Installation oder in der wsconfig.xml-Datei geändert werden. Port-Konflikte sind auf Datacenter-Hosts üblich, auf denen verschiedene Management-Applikationen ausgeführt werden. Bei den integrierten Webservices kann der Port des Controllers nicht geändert werden. Standardmäßig ist der Port 8443 für sichere Verbindungen verfügbar. |
API-Pfad
|
Eine Anforderung wird an eine bestimmte REST-Ressource oder einen bestimmten Endpunkt innerhalb der Web Services-API gestellt. Die meisten Endpunkte sind in Form von:
Der API-Pfad besteht aus drei Teilen:
|
Unterstützte HTTP-Verben
Unterstützte HTTP-Verben umfassen ABRUFEN, POST und LÖSCHEN:
-
GET-Anforderungen werden für schreibgeschützte Anfragen verwendet.
-
POST-Requests werden zum Erstellen und Aktualisieren von Objekten sowie für Leseanforderungen verwendet, die möglicherweise Auswirkungen auf die Sicherheit haben.
-
LÖSCHANFRAGEN werden normalerweise verwendet, um ein Objekt aus dem Management zu entfernen, ein Objekt vollständig zu entfernen oder den Status des Objekts zurückzusetzen.
|
Derzeit unterstützt die Web Services API PUT oder PATCH nicht. Stattdessen können Sie POST verwenden, um die typischen Funktionen für diese Verben bereitzustellen. |
Kopfzeilen akzeptieren
Wenn ein Anforderungsentext zurückgegeben wird, gibt Web Services die Daten im JSON-Format zurück (sofern nicht anders angegeben). Bestimmte Clients haben standardmäßig die Anforderung von „Text/HTML“ oder etwas ähnlichem. In diesen Fällen antwortet die API mit einem HTTP-Code 406 und bezeichnet, dass sie keine Daten in diesem Format bereitstellen kann. Als Best Practice sollten Sie den Header akzeptieren für alle Fälle als „Application/json“ definieren, in denen Sie JSON als Antworttyp erwarten. In anderen Fällen, in denen ein Antwortkörper nicht zurückgegeben wird (z. B. LÖSCHEN), verursacht die Annahme-Kopfzeile keine unbeabsichtigten Auswirkungen.
Antworten
Wenn eine Anfrage an die API gestellt wird, gibt eine Antwort zwei wichtige Informationen zurück:
-
HTTP-Statuscode — gibt an, ob die Anforderung erfolgreich war.
-
Optionaler Antwortkörper — bietet in der Regel einen JSON-Körper, der den Zustand der Ressource oder eines Körpers darstellt, der mehr Details über die Art eines Fehlers liefert.
Sie müssen den Statuscode und den Inhaltstyp-Header überprüfen, um festzustellen, wie der resultierende Antwortkörper aussieht. Für HTTP-Statuscodes 200-203 und 422 gibt Web Services einen JSON-Text mit der Antwort zurück. Bei anderen HTTP-Statuscodes gibt Web Services in der Regel keinen zusätzlichen JSON-Text zurück, entweder weil die Spezifikation es nicht zulässt (204) oder weil der Status selbsterklärend ist. In der Tabelle sind allgemeine HTTP-Statuscodes und -Definitionen aufgeführt. Sie gibt außerdem an, ob Informationen, die mit den einzelnen HTTP-Codes in einem JSON-Körper verbunden sind, zurückgegeben werden.
| HTTP-Statuscode | Beschreibung | JSON-Text |
|---|---|---|
200 OK |
Kennzeichnet eine erfolgreiche Antwort. |
Ja. |
201 Erstellt |
Gibt an, dass ein Objekt erstellt wurde. Dieser Code wird in einigen seltenen Fällen anstelle eines 200-Status verwendet. |
Ja. |
202 Akzeptiert |
Gibt an, dass die Anforderung zur Bearbeitung als asynchrone Anforderung akzeptiert wird, Sie müssen jedoch eine nachfolgende Anfrage stellen, um das tatsächliche Ergebnis zu erhalten. |
Ja. |
203 Nicht-Autorisierende Informationen |
Ähnlich wie bei einer Antwort von 200, Webservices können jedoch nicht garantieren, dass die Daten aktuell sind (beispielsweise sind derzeit nur zwischengespeicherte Daten verfügbar). |
Ja. |
204 Kein Inhalt |
Zeigt eine erfolgreiche Operation an, aber es gibt keinen Antwortkörper. |
Nein |
400 Fehlerhafte Anfrage |
Gibt an, dass der in der Anforderung angegebene JSON-Text nicht gültig ist. |
Nein |
401 Nicht Autorisiert |
Zeigt an, dass ein Authentifizierungsfehler aufgetreten ist. Es wurden keine Anmeldedaten angegeben oder der Benutzername oder das Passwort war ungültig. |
Nein |
403 Verbotene |
Ein Autorisierungsfehler, der angibt, dass der authentifizierte Benutzer nicht über die Berechtigung zum Zugriff auf den angeforderten Endpunkt verfügt. |
Nein |
404 Nicht Gefunden |
Zeigt an, dass die angeforderte Ressource nicht gefunden werden konnte. Dieser Code ist gültig für nicht vorhandene APIs oder nicht vorhandene Ressourcen, die durch die Kennung angefordert werden. |
Nein |
422 Nicht Verarbeitbare Einheit |
Gibt an, dass die Anforderung in der Regel gut geformt ist, jedoch sind die Eingabeparameter ungültig oder der Status des Speichersystems erlaubt Web Services nicht, die Anforderung zu erfüllen. |
Ja. |
424 Abhängigkeit Fehlgeschlagen |
Wird im Web Services Proxy verwendet, um anzuzeigen, dass das angeforderte Speichersystem derzeit nicht verfügbar ist. Daher können Web Services die Anforderung nicht erfüllen. |
Nein |
429 Zu Viele Anfragen |
Gibt an, dass eine Antragsbegrenzung überschritten wurde und zu einem späteren Zeitpunkt erneut versucht werden sollte. |
Nein |
Beispielskripts
GitHub enthält ein Repository für die Sammlung und Organisation von Beispielskripten, die die Verwendung der NetApp SANtricity Web Services API veranschaulichen. Informationen zum Zugriff auf das Repository finden Sie unter "Beispiele für NetApp Webservices".