REST

In aggiunta ai servizi API in stile RPC, SoftLayer fornisce un'API RESTful. Utilizza l'API REST nei casi in cui il tuo linguaggio di programmazione potrebbe non avere un buon supporto SOAP o XML-RPC ma può eseguire delle semplici azioni di protocollo HTTP e può interpretare i dati XML o JSON.

URL REST

Gli URL dell'API REST sono strutturati per attraversare facilmente la gerarchia oggetti di SoftLayer. Una richiesta REST di base è strutturata nel seguente modo:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • Tutte le richieste REST, anche le richieste di rete privata, devono essere passate tramite SSL HTTP.
  • Utilizza la tua chiave e il tuo nome utente API per autenticare la tua richiesta tramite l'autenticazione HTTP.
  • Il nome host e il nome cartella di base per una richiesta REST è api.softlayer.com/rest/v3/ o api.service.softlayer.com/rest/v3/. Utilizza api.service.softlayer.com/rest/v3/ per accedere all'API REST sulla rete privata di SoftLayer. È un modo più sicuro per comunicare con SoftLayer, ma il sistema che effettua le chiamate API si deve trovare sulla rete privata di SoftLayer (acquistato da SoftLayer o che ha eseguito l'accesso tramite VPN alla rete privata di SoftLayer).
  • Fai seguire all'URL di base il nome del servizio API che vuoi richiamare, ad esempio "SoftLayer_Account" o "SoftLayer_Hardware_Server".
  • Se la tua richiesta API richiede un parametro di inizializzazione, aggiungi una barra seguita dall'id del parametro init al tuo URL.
  • L'API REST SoftLayer può restituire output in formato XML o JSON. Aggiungi ".xml" o ".json" alla fine della tua richiesta per specificare qual è il formato in cui preferisci ricevere i dati.

Una richiesta come questa richiama il metodo getObject() del servizio API che stai provando a richiamare. SoftLayer_Account::getObject non richiede un parametro di inizializzazione, quindi il suo URL REST si presenta così:

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

Tuttavia, per richiamare il metodo getObject() per uno
specifico metodo SoftLayer_Hardware_Server, utilizza il seguente URL, presumendo che "1234" sia
l'ID del server che desideri richiamare:

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

Richiama i metodi API diversi da getObject() inserendo il nome del metodo dopo il tuo parametro di inizializzazione. Se il tuo metodo inizia per "get", rimuovi la parola "get" dal nome del metodo e converti la sua prima lettera in maiuscolo. Questo metodo può essere utilizzato anche per accedere rapidamente alle proprietà relazionali di un oggetto. Ad esempio, il metodo getHardware() e la proprietà relazionale hardware nel servizio API SoftLayer_Account possono essere raggiunti a:

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

In modo analogo, i componenti di rete di un server possono essere raggiunti al seguente URL:

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

Concatena una combinazione di ID parametro di inizializzazione e di proprietà relazionali per eseguire il drill-down in specifici componenti oggetto. Ogni ID aggiunto eseguirà il drill-down nella specifica proprietà relazionale indicata. Ad esempio, se vuoi ottenere il componente di rete del server 1234 con ID 5678, utilizza l'URL:

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

E per ottenere la connessione uplink del componente di rete:

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

Tipi di richiesta HTTP

DELETE

Utilizza una richiesta HTTP DELETE per eliminare un oggetto invece del metodo deleteObject() di un servizio. Passa, ad esempio, una richiesta HTTP DELETE al seguente URL per rimuovere il record di dominio 1234 dai server DNS di SoftLayer.

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

GET

Utilizza le richieste HTTP GET per semplici chiamate di metodo e di richiamo di oggetti. Ad esempio, richiama l'ID di record di dominio 1234 con una richiesta HTTP GET all'URL:

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

POST

Utilizza una richiesta HTTP POST per creare un oggetto invece dei metodi createObject() o createObjects() di un servizio. Esegui il POST di una singola struttura JSON o XML che contiene un singolo elemento denominato "parameter" che contiene la struttura essenziale del tuo oggetto e gli eventuali altri parametri richiesti dal metodo createObject() del tuo servizio API. Passa, ad esempio, una richiesta HTTP POST con i seguenti dati al seguente URL per creare un record di dominio nei server DNS di SoftLayer.

{
    "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

Utilizza una richiesta HTTP PUT per modificare un oggetto invece dei metodi editObject() o editObjects() di un servizio. Esegui il PUT di una singola struttura JSON o XML che contiene un singolo elemento denominato "parameter" che contiene la struttura essenziale del tuo oggetto e gli eventuali altri parametri richiesti dal metodo editObject() del tuo servizio API. Ad esempio, passa una richiesta HTTP PUT con i seguenti dati al seguente URL per modificare il record di risorsa dominio 5678 nel record di dominio 1234 sui server DNS di SoftLayer, cambiando il suo valore data in "10.0.0.1".

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

Passaggio dei parametri di metodo

I parametri vengono passati nella nostra API REST accodando ciascuno di essi al percorso dell'URL.
Devono essere passati nello stesso ordine in cui sono elencati nella documentazione per ciascun metodo, dall'alto al basso.

Ad esempio, SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber richiede il parametro userRecordId:

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

Alcuni metodi richiederanno un singolo parametro che è un array, come SoftLayer_Dns_Domain_ResourceRecord::createObjects:

 {
  "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"}
      ]
    ]
}

Modi alternativi per impostare i formati di parametri e restituzioni

Oltre ad aggiungere ".json" e ".xml" al tuo URL REST, puoi anche impostare i formati di restituzione delle chiamate API passando un MIME-type (application/json per JSON e text/xml per XML) nelle intestazioni HTTP Accept o Content-Type nella tua richiesta.

Utilizzo delle maschere oggetto

Crea una maschera oggetto nel tuo URL di chiamata API aggiungendo una variabile objectMask alla tua stringa di query. Le maschere oggetto sono un elenco separato da caratteri punto e virgola di proprietà relazionali, con le proprietà relazionali concatenate separate da punti. Per risparmiare spazio nella stringa di query, le maschere oggetto REST sono relative al tipo di dati alla fine del tuo URL invece che al servizio API che stai interrogando. In modo analogo, le maschere oggetto REST non contengono una proprietà mask.

Il seguente URL crea una maschera oggetto che richiama i record hardware di un account insieme ai centri dati in cui tale hardware si trova. Nota che la maschera oggetto contiene solo la proprietà relazionale che vogliamo richiamare correlata all'hardware, non il nostro account.

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

Questo URL ottiene i record hardware di un account insieme ai record di datacenter, sistema operativo e componente di rete associati di detto hardware. Nota che questi elementi relazionali sono separati da caratteri punto e virgola.

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

Questo URL ottiene i record hardware di un account insieme ai record di datacenter, sistema operativo, password del sistema operativo e componente di rete associati di detto hardware. Le proprietà relazionali concatenate sono separate da punti.

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

L'API REST può gestire le maschere oggetto in un modo leggermente diverso rispetto alle API XML-RPC e SOAP di SoftLayer. È possibile creare delle maschere oggetto REST per filtrare le proprietà di tipi di dati locali richiamate dall'API SoftLayer. Se definisci una proprietà locale nella tua maschera, l'API SoftLayer tratta la tua maschera come un filtro e richiamerà solo le proprietà locali specificate nella tua maschera. Ad esempio, questo URL richiama solo le proprietà id e hostname nei record hardware di un account:

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

Utilizzo dei limiti dei risultati

Limita il numero di risultati in una chiamata API aggiungendo una variabile resultLimit alla tua stringa di query. Imposta la tua variabile resultLimit su un insieme separato da virgole di due numeri:

  • L'offset a cui iniziare il tuo insieme dei risultati.
  • Il numero di risultati a cui limitare la tua chiamata.

Questo URL recupera i primi due ticket aperti su un account, richiamando il metodo SoftLayer_Account::getOpenTickets:

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

Gestione degli errori

L'API REST SoftLayer restituisce l'output XML o JSON con un singolo nodo error che contiene gli eventuali messaggi di errore restituiti dalla tua chiamata API. Ad esempio, l'URL a un servizio inesistente:
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
restituisce l'errore:

>
   Service does not exist>
>

Mentre il suo equivalente JSON:

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

restituisce l'errore:

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

Errori di autenticazione

L'API REST SoftLayer restituisce un errore HTTP 401 - Non autorizzato se, quando si richiede un URL REST, viene utilizzata una combinazione nome utente/chiave API non valida.

Avvertenze

Specifica di tipi complessi

Come con XML-RPC, l'API REST non può determinare i tipi complessi estesi, in certi parametri. In questi casi, devi definire una proprietà complexType nei tuoi parametri complessi che sia impostata sul tipo di oggetto che stai inviando al tuo metodo.

Componenti API a cui si fa riferimento

Servizi

Tipi di dati

Metodi