REST

SoftLayer proporciona una API RESTful además de los servicios de API de tipo RPC. Utilice la API REST en aquellos casos en los que el lenguaje de programación no tenga un buen soporte SOAP o XML-RPC, pero en los que pueda ejecutar acciones simples de protocolo HTTP e interpretar los datos XML o JSON.

URL de REST

Los URL de la API REST se estructuran para atravesar fácilmente la jerarquía de objetos de SoftLayer. Una solicitud REST básica se estructura de la siguiente manera:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • Todas las solicitudes REST, incluso las solicitudes de red privada, deben pasar por SSL HTTP.
  • Utilice su nombre de usuario y clave de API para autenticar la solicitud mediante la autenticación HTTP.
  • El nombre de host base y el nombre de carpeta de una solicitud REST es api.softlayer.com/rest/v3/ o api.service.softlayer.com/rest/v3/. Utilice api.service.softlayer.com/rest/v3/ para acceder a la API REST en la red privada de SoftLayer. Es una forma más segura de comunicarse con SoftLayer, pero el sistema que realiza las llamadas de API debe estar en la red privada de SoftLayer (adquirida en SoftLayer o con una sesión iniciada en la VPN de red privada de SoftLayer).
  • Siga el URL base con el nombre del servicio de API que desea invocar, por ejemplo, "SoftLayer_Account" o "SoftLayer_Hardware_Server".
  • Si la solicitud de API requiere un parámetro de inicialización, añada al URL una barra inclinada seguida del ID del parámetro init.
  • La API REST de SoftLayer puede devolver una salida con formato XML o JSON. Añada ".xml" o ".json" al final de la solicitud para especificar con qué formato desea recibir los datos.

Una solicitud como esta invoca el método getObject() del servicio de API que está intentando invocar. SoftLayer_Account::getObject no requiere un parámetro de inicialización, por lo que el URL de REST es como el siguiente:

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

No obstante, para invocar el método getObject() para un registro de SoftLayer_Hardware_Server específico, utilice el siguiente URL, suponiendo que "1234" es el ID del servidor que desea recuperar:

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

Para invocar los métodos de API distintos de getObject(), coloque el nombre del método después del parámetro de inicialización. Si el método empieza por "get", elimine la palabra "get" del nombre de método y cambie la primera letra a mayúsculas. Este método también puede utilizarse para acceder rápidamente a las propiedades relacionales de un objeto. Por ejemplo, el método getHardware() y la propiedad relacional hardware en el servicio de API de SoftLayer_Account pueden alcanzarse en:

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

De forma parecida, los componentes de red de un servidor pueden alcanzarse en el siguiente URL:

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

Encadene una combinación de ID de parámetro de inicialización y propiedades relacionales para detallar más componentes de objetos específicos. Cada ID añadido detallará más esa propiedad relacional específica. Por ejemplo, si desea obtener el componente de red del servidor 1234 con el ID 5678, utilice el URL:

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

Para obtener la conexión de enlace ascendente de ese componente de red:

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

Tipos de solicitud HTTP

DELETE

Utilice una solicitud HTTP DELETE para suprimir un objeto, en lugar del método deleteObject() de un servicio. Por ejemplo, pase una solicitud HTTP DELETE al siguiente URL para poder eliminar el registro de dominio 1234 de los servidores DNS de SoftLayer.

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

GET

Utilice solicitudes HTTP GET para las llamadas de método y la recuperación simple de objetos. Por ejemplo, recupere el ID de registro de dominio 1234 con una solicitud HTTP GET al URL:

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

POST

Utilice una solicitud HTTP POST para crear un objeto, en lugar de los métodos createObject() o createObjects() de un servicio. Ejecute POST en una estructura JSON o XML individual que contenga un único elemento denominado "parameters" que contenga la estructura de esqueleto del objeto y cualquier otro parámetro necesario para el método createObject() del servicio de API. Por ejemplo, pase una solicitud HTTP POST con los siguientes datos al siguiente URL para poder crear un registro de dominio en los servidores DNS de 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

Utilice una solicitud HTTP PUT para editar un objeto, en lugar de los métodos editObject() o editObjects() de un servicio. Ejecute PUT en una estructura JSON o XML individual que contenga un único elemento denominado "parameters" que contenga la estructura de esqueleto del objeto y cualquier otro parámetro necesario para el método editObject() del servicio de API. Por ejemplo, pase una solicitud HTTP PUT con los siguientes datos al siguiente URL para poder editar el registro de recurso de dominio 5678 en el registro de dominio 1234 en los servidores DNS de SoftLayer, cambiando data por "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

Cómo pasar parámetros de método

Los parámetros se pasan en la API REST añadiendo cada uno a la vía de acceso del URL.
Deben pasarse en el mismo orden con el que se listan en la documentación de cada método, de arriba abajo.

Por ejemplo, SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber requiere el parámetro userRecordId:

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

Algunos métodos solicitarán un parámetro individual que es una matriz como, por ejemplo, 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"}
      ]
    ]
}

Formas alternativas de establecer formatos de devolución y parámetros

Además de añadir ".json" y ".xml" al URL de REST, también puede establecer formatos de devolución de llamada de API pasando un tipo MIME (application/json para JSON y text/xml para XML) en las cabeceras HTTP Accept o Content-Type de la solicitud.

Utilización de máscaras de objeto

Cree una máscara de objeto en la llamada de API añadiendo una variable objectMask a la serie de consulta. Las máscaras de objeto son una lista delimitada por punto y coma de propiedades relacionales, donde las propiedades relacionales encadenadas están separadas por puntos. Para ahorrar espacio en la serie de consulta, las máscaras de objeto REST son relativas al tipo de datos al final del URL, en lugar de al servicio de API que está consultando. De la misma manera, las máscaras de objeto REST no contienen una propiedad mask.

El siguiente URL crea una máscara de objeto que recupera los registros de hardware de una cuenta, junto con los centros de datos donde se ubica ese hardware. Observe que la máscara de objeto sólo contiene la propiedad relacional que deseamos recuperar relacionada con el hardware, no nuestra cuenta.

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

Este URL obtiene los registros de hardware de una cuenta, junto con los registros de centro de datos, sistema operativo y componentes de red asociados del hardware. Observe que estos elementos relacionales están separados por punto y coma.

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

Este URL obtiene los registros de hardware de una cuenta, junto con los registros de centro de datos, sistema operativo, contraseña de sistema operativo y componentes de red asociados del hardware. Las propiedades relacionales encadenadas están separadas por puntos.

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

La API REST puede manejar máscaras de objeto de forma ligeramente diferente a las API SOAP y XML-RPC de SoftLayer. Pueden crearse máscaras de objeto REST para filtrar las propiedades de tipos de datos locales recuperadas de la API de SoftLayer. Si define una propiedad local en la máscara, la API de SoftLayer trata la máscara como un filtro y sólo recupera las propiedades locales especificadas en la máscara. Por ejemplo, este URL sólo recupera las propiedades id y hostname en los registros de hardware de una cuenta:

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

Utilización de los límites de resultados

Para limitar el número de resultados en una llamada de API, añada una variable resultLimit a la serie de consulta. Establezca la variable resultLimit en un conjunto delimitado por comas de dos números:

  • El desplazamiento en el que se inicia el conjunto de resultados.
  • El número de resultados al que se limita la llamada.

Este URL recupera los primeros dos tíquets abiertos en una cuenta, invocando el método SoftLayer_Account::getOpenTickets:

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

Manejo de errores

La API REST de SoftLayer devuelve una salida XML o JSON con un nodo de error individual que contiene los mensajes de error devueltos por la llamada de API. Por ejemplo, el URL al servicio no existente:
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
devuelve el error:

>
   Service does not exist>
>

Mientras que su equivalente de JSON:

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

devuelve el error:

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

Errores de autenticación

La API REST de SoftLayer devuelve un error HTTP 401 No autorizado si se utiliza una combinación no válida de nombre de usuario/clave de API cuando se solicita el URL de REST.

Advertencias

Especificación de tipos complejos

Al igual que con XML-RPC, la API REST no puede determinar los tipos complejos ampliados en determinados parámetros. En estos casos, debe definir una propiedad complexType del conjunto de parámetros complejos en el tipo de objeto que está enviando al método.

Componentes de API referenciados

Servicios

Tipos de datos

Métodos