REST

SoftLayer bietet zusätzlich zu den API-Services im RPC-Stil eine REST-konforme API. Verwenden Sie die REST-API in Fällen, in denen Ihre Programmiersprache möglicherweise keine gute SOAP- oder XML-RPC-Unterstützung hat, aber einfache HTTP-Protokollaktionen durchführen und XML- oder JSON-Daten interpretieren kann.

REST-URLs

REST-konforme API-URLs sind strukturiert, um die SoftLayer-Objekthierarchie ganz einfach traversieren zu können. Eine grundlegende REST-Anforderung ist wie folgt strukturiert:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • Alle REST-Anforderungen, selbst Anforderungen privater Netzwerke, müssen über HTTP-SSL weitergeleitet werden.
  • Verwenden Sie Ihren API-Benutzernamen und -Schlüssel, um Ihre Anforderung durch HTTP-Authentifizierung zu authentifizieren.
  • Der grundlegende Hostname und Ordnername für eine REST-Anforderung ist entweder api.softlayer.com/rest/v3/ oder api.service.softlayer.com/rest/v3/. Verwenden Sie api.service.softlayer.com/rest/v3/, um über das private Netzwerk von SoftLayer auf die REST-API zuzugreifen. Es ist eine sichere Möglichkeit, mit SoftLayer zu kommunizieren. Das System, von dem API-Aufrufe ausgehen, muss sich jedoch im privaten Netzwerk von SoftLayer befinden (entweder bei SoftLayer erworben oder im privaten Netzwerk VPN von SoftLayer angemeldet).
  • Erweitern Sie die Basis-URL mit dem Namen des API-Service, den Sie aufrufen möchten, z. B. „SoftLayer_Account“ oder „SoftLayer_Hardware_Server“.
  • Wenn Ihre API-Anforderung einen Initialisierungsparameter erfordert, fügen Sie Ihrer URL einen Schrägstrich gefolgt von Ihrer Initialisierungsparameter-ID hinzu.
  • Die REST-API von SoftLayer kann Ausgabe entweder in XML- oder JSON-Format zurückgeben. Fügen Sie am Ende Ihrer Anforderung „.xml“ oder „.json“ hinzu, um anzugeben, in welchem Format Sie Daten erhalten möchten.

Eine Anforderung wie diese ruft die Methode getObject() des API-Service auf, den Sie aufrufen möchten. SoftLayer_Account::getObject erfordert keinen Initialisierungsparameter, also sieht die entsprechende REST-URL wie folgt aus:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account.json

Verwenden Sie jedoch zum Aufrufen der getObject()-Methode für einen bestimmten SoftLayer_Hardware_Server-Datensatz die folgende URL, wobei „1234“ die ID des Servers ist, den Sie abrufen möchten:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234.json

Sie können andere API-Methoden als getObject() aufrufen, indem Sie den Namen der Methode hinter Ihren Initialisierungsparameter setzen. Wenn Ihre Methode mit „get“ beginnt, entfernen Sie das Wort „get“ aus dem Methodennamen und ändern Sie den ersten Buchstaben in Großschreibung. Diese Methode kann auch verwendet werden, um schnell auf die relationalen Eigenschaften eines Objekts zuzugreifen. Zum Beispiel kann die Methode getHardware() und die relationale Eigenschaft hardware im API-Service SoftLayer_Account wie folgt erreicht werden:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json

Gleichermaßen können die Netzwerkkomponenten eines Servers unter der folgenden URL erreicht werden:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents.json

Verketten Sie eine Kombination aus Initialisierungsparameter-IDs und relationalen Eigenschaften, um einen Drilldown in bestimmten Objektkomponenten durchzuführen. Jede hinzugefügte ID führt eine Drilloperation in der jeweiligen relationalen Eigenschaft durch. Wenn Sie beispielsweise die Netzwerkkomponente des Servers 1234 mit der ID 5678 abrufen möchten, verwenden Sie folgende URL:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678.json

Und um die Uplinkverbindung dieser Netzwerkkomponente abzurufen:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678/uplinkNetworkComponents.json

HTTP-Anforderungstypen

DELETE

Verwenden Sie eine HTTP-DELETE-Anforderung, um ein Objekt zu löschen, statt der Methode deleteObject() eines Service. Leiten Sie z. B. eine HTTP-DELETE-Anforderung an die folgende URL weiter, um den Domänendatensatz 1234 aus den DNS-Servern von SoftLayer zu entfernen.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

GET

Verwenden Sie HTTP-GET-Anforderungen, um Objektabruf und Methodenaufrufe zu vereinfachen. Rufen Sie z. B. die Domänendatensatz-ID 1234 mit einer HTTP-GET-Anforderung an die URL ab:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

POST

Verwenden Sie eine HTTP-POST-Anforderung, um ein Objekt zu erstellen, statt der Methoden createObject() oder createObjects() eines Service. ERSTELLEN Sie eine einzige JSON- oder XML-Struktur, die ein einziges Element mit dem Namen „parameters“ enthält, das wiederum die Gerüststruktur Ihres Objekts und sonstige Parameter enthält, die für die createObject()-Methode Ihres API-Service erforderlich sind. Leiten Sie z. B. eine HTTP-POST-Anforderung mit den folgenden Daten an die folgende URL weiter, um einen Domänendatensatz in den DNS-Servern von SoftLayer zu erstellen.

{
    "parameters" : [
        {
            "name" : "example.org",
            "resourceRecords" : [
                {
                    "type" : "a",
                    "host" : "@",
                    "data" : "127.0.0.1"
                }
            ]
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain.json

PUT

Verwenden Sie eine HTTP-PUT-Anforderung, um ein Objekt zu bearbeiten, statt der Methoden editObject() oder editObjects() eines Service. BEARBEITEN Sie eine einzige JSON- oder XML-Struktur, die ein einziges Element mit dem Namen „parameters“ enthält, das wiederum die Gerüststruktur Ihres Objekts und sonstige Parameter enthält, die für die editObject()-Methode Ihres API-Service erforderlich sind. Leiten Sie z. B. eine HTTP-PUT-Anforderung mit den folgenden Daten an die folgende URL weiter, um den Domänenressourcendatensatz 5678 im Domänendatensatz 1234 auf den DNS-Servern von SoftLayer zu bearbeiten und data in „10.0.0.1“ zu ändern.

{
    "parameters" : [
        {
            "data" : "10.0.0.1",
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234/ResourceRecords/5678.json

Weitergabe von Methodenparametern

Parameter werden in der REST-API weitergegeben, indem sie jeweils an den Pfad der URL angehängt werden.
Sie sollten in derselben Reihenfolge weitergegeben werden, in der sie in der Dokumentation für die jeweiligen Methoden von oben nach unten aufgeführt sind.

Zum Beispiel ist für SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber der Parameter userRecordId erforderlich:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Monitoring_Agent/1234/setActiveAlarmSubscriber/5678.json

Einige Methoden fordern einen einzigen Parameter an, bei dem es sich um ein Array wie SoftLayer_Dns_Domain_ResourceRecord::createObjects handelt:

 {
  "parameters":
    [
      [
        {"host":"hosta","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
        ,
        {"host":"hostb","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
      ]
    ]
}

Alternative Möglichkeiten, um Parameter und Rückgabeformate festzulegen

Zusätzlich zum Hinzufügen von „.json“ und „.xml“ zu Ihrer REST-URL können Sie auch Rückgabeformate für API-Aufrufe festlegen, indem Sie einen MIME-Typ (application/json für JSON und text/xml für XML) in den HTTP-Headern Accept oder Content-Type in Ihrer Anforderung weitergeben.

Verwendung von Objektmasken

Erstellen Sie eine Objektmaske in der URL Ihres API-Aufrufs, indem Sie Ihrer Abfragezeichenfolge eine objectMask-Variable hinzufügen. Bei einer Objektmaske handelt es sich um eine durch Semikolons abgetrennte Liste relationaler Eigenschaften mit verketteten relationalen Eigenschaften, die durch Punkte voneinander getrennt sind. Damit Platz in der Abfragezeichenfolge gespart werden kann, beziehen sich die REST-Objektmasken auf den Datentyp am Ende Ihrer URL statt auf den API-Service, den Sie abfragen. REST-Objektmasken enthalten auch keine mask-Eigenschaft.

Die folgende URL erstellt eine Objektmaske, die die Hardwaredatensätze eines Accounts sowie die Rechenzentren, in denen sich diese Hardware befindet, abruft. Bitte berücksichtigen Sie, dass die Objektmaske nur die relationale Eigenschaft enthält, die in Bezug auf die Hardware, nicht in Bezug auf den Account abgerufen werden soll.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter

Diese URL ruft die Hardwaredatensätze eines Accounts sowie die zugehörigen Datensätze bezüglich Rechenzentrum, Betriebssystem und Netzwerkkomponente dieser Hardware ab. Bitte berücksichtigen Sie, dass diese relationalen Elemente durch Semikolons voneinander getrennt sind.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem;networkComponents

Diese URL ruft die Hardwaredatensätze eines Accounts sowie die zugehörigen Datensätze bezüglich Rechenzentrum, Betriebssystem, Betriebssystemkennwort und Netzwerkkomponente dieser Hardware ab. Verkettete relationale Eigenschaften sind durch Punkte voneinander getrennt.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem.passwords;networkComponents

Die REST-API kann mit Objektmasken geringfügig anders verfahren als die SOAP- und XML-RPC-APIs von SoftLayer. REST-Objektmasken können so eingestellt werden, dass sie lokale Datentypeigenschaften, die von der SoftLayer-API abgerufen werden, filtern. Wenn Sie in Ihrer Maske eine lokale Eigenschaft definieren, behandelt die SoftLayer-API Ihre Maske wie einen Filter und ruft nur die in Ihrer Maske angegebenen lokalen Eigenschaften ab. Beispielsweise ruft diese URL nur die ID- und Hostnameneigenschaften in den Hardwaredatensätzen eines Accounts ab:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=hardware.id;hardware.hostname

Verwendung von Ergebnisbegrenzungen

Begrenzen Sie die Anzahl Ergebnisse in einem API-Aufruf, indem Sie Ihrer Abfragezeichenfolge eine resultLimit-Variable hinzufügen. Legen Sie Ihre resultLimit-Variable auf zwei durch Kommas abgetrennte Zahlen fest:

  • Den Offset, an dem die Ergebnisliste beginnen soll.
  • Die Anzahl Ergebnisse, auf die der Aufruf begrenzt werden soll.

Diese URL ruft die ersten beiden offenen Tickets eines Accounts ab und ruft dafür die Methode SoftLayer_Account::getOpenTickets auf:

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/OpenTickets.json?resultLimit=0,2

Fehlerbehandlung

Die REST-API von SoftLayer gibt eine Ausgabe in XML- oder JSON-Format mit einem einzigen error-Knoten zurück, der alle Fehlernachrichten enthält, die Ihr API-Aufruf zurückgegeben hat. Beispiel: Die URL zum nicht vorhandenen Service:
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
gibt folgenden Fehler zurück:

>
   Service does not exist>
>

Die URL in JSON-Format:

https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.json

gibt folgenden Fehler zurück:

{
    "error": "Service does not exist"
}

Authentifizierungsfehler

Die REST-API von SoftLayer gibt den Fehler „HTTP 401 Unauthorized“ zurück, wenn bei der Anforderung einer REST-URL eine ungültige Kombination aus Benutzername/API-Schlüssel verwendet wird.

Ausschlüsse

Komplexe Typen angeben

Wie bei XML-RPC kann auch die REST-API keine erweiterten komplexen Typen in bestimmten Parametern feststellen. In diesen Fällen sollten Sie in Ihren komplexen Parametern eine complexType-Eigenschaft definieren, die auf den Objekttyp festgelegt ist, den Sie an Ihre Methode senden.

Referenzierte API-Komponenten

Services

Datentypen

Methoden