Visión general de la API de SoftLayer

La interfaz de programación de aplicaciones (API) de SoftLayer es la interfaz de desarrollo que proporciona a los desarrolladores y administradores del sistema una interacción directa con el sistema de fondo de SoftLayer. La funcionalidad expuesta por esta API permite a los usuarios realizar la gestión de servidores remotos, la supervisión y la recuperación de información de varios sistemas de SoftLayer, por ejemplo, la contabilidad, el inventario y DNS. Muchas de las características del Portal de clientes de SoftLayer se basan en esta API, lo que normalmente significa que si una interacción es posible en el Portal de clientes, puede ejecutarse también en nuestra API.

¿Quién debe utilizar la API?

La API de SoftLayer (SLAPI) está disponible para todos los clientes de SoftLayer sin cargo adicional. Animamos a nuestros clientes con un conocimiento básico en programación orientada a objetos a aprovechar todas las prestaciones que ofrece la SLAPI. Mientras los clientes de SoftLayer utilizan la SLAPI para una amplia variedad de tareas, la capacidad de interactuar mediante programación con todas las partes del entorno de SoftLayer en la API permite que la mayoría de nuestros clientes utilicen la SLAPI para automatizar las tareas.

Utilización de la API de SoftLayer

Antes de empezar

La SLAPI proporciona a los usuarios una interacción directa con los objetos que ejecutan el Portal de clientes. Antes de desarrollar la SLAPI, se recomienda especialmente conocer conceptos básicos de programación orientada a objetos como, por ejemplo, los objetos, las propiedades, los métodos y la herencia. Los métodos de la SLAPI se ejecutan con objetos de servicio en nuestros sistemas de fondo, lo que devuelve objetos de tipos de datos específicos de SoftLayer y tipos de datos estándar como enteros, booleanos y series.
La SLAPI es un sistema de llamada a procedimiento remoto. Cada llamada implica el envío de datos a un punto final de API a cambio de la recepción de datos estructurados. El formato utilizado para enviar y recibir datos con la SLAPI depende de qué implementación de la API utilice. La SLAPI utiliza actualmente SOAP, XML-RPC o REST para la transmisión de datos. Antes de realizar llamadas de API, se recomienda conocer cómo utilizar estos protocolos en su lenguaje de script o programación. Puede utilizar cualquiera de estas implementaciones en su aplicación. También proporcionamos varios clientes de API específicos del servicio, que están disponibles en una amplia variedad de lenguajes soportados en nuestro perfil de github.

Creación de un usuario de API

Toda llamada a la SLAPI se autentica con una cuenta del Portal de clientes. Las cuentas en el Portal de clientes pueden contener varios usuarios y se recomienda especialmente crear un usuario exclusivo del Portal de clientes para ejecutar las llamadas de API. Tanto si desarrolla una aplicación como si utiliza una aplicación basada en la API desarrollada por otros, debe autenticarse en el programa para acceder a la información e interactuar con cualquier aspecto de la cuenta. La autenticación en la SLAPI requiere un nombre de usuario y una clave de API del Portal de clientes, una señal de autenticación especial reservada para las llamadas de método de API. Los permisos de usuario definidos en el Portal de clientes se reflejan en las llamadas de API.

Elección de la red pública o privada

Los servidores de punto final de SLAPI existen en las redes públicas y privadas de SoftLayer. Las aplicaciones basadas en API pueden conectarse desde cualquier host en Internet; no obstante, la red privada de SoftLayer ofrece una capa adicional de seguridad de datos. Asimismo, SoftLayer ofrece una amplia variedad de puntos finales de API de red privada, a los que sólo se puede acceder si está conectado a la red privada. Todos los servidores e instancias de sistema asociados con una cuenta de SoftLayer tienen una conexión directa a la red privada y no requieren una autenticación adicional. Si desea utilizar puntos finales privados de otro dispositivo, se requiere una conexión VPN con nuestra red privada.

Conceptos básicos de API

Servicios

Un servicio es un punto final asociado con los sistemas de SoftLayer internos. Cada servicio es una colección de métodos o acciones que pueden ejecutarse. Puede encontrar una lista de todos los servicios de SLAPI en la sección Referencia de este sitio.
Cuando accede a la sección Servicios de la API deseada, aparece una lista de todos los servicios disponibles a la izquierda de la pantalla. Todos los servicios de SoftLayer empiezan por "SoftLayer_" y contienen términos adicionales que definen la función general que proporciona el servicio: "Hardware", "Account", "Billing", "Network", etc. A partir de aquí, cada servicio se amplía con un nombre que define la función específica del servicio en ese subconjunto particular. Cada servicio asociado con la API de SoftLayer tiene un nombre exclusivo. Aunque algunos servicios como SoftLayer_Account y SoftLayer_Account_Address compartan un prefijo común, su interacción no es necesariamente similar y no hay ninguna herencia directa para los servicios con un nombre similar. Debido a ello, cada servicio debe abordarse individualmente.
Para ver los detalles de un determinado servicio, pulse el nombre de servicio. La página de cada servicio incluye una lista de los métodos disponibles para ese servicio y también puede incluir una breve descripción general del servicio. Aunque cada servicio ofrece un conjunto exclusivo de métodos, muchos servicios ofrecen el método getObject. Estos métodos pueden utilizarse para recuperar un objeto del mismo tipo de la API. Por ejemplo, la invocación del método getObject en el servicio SoftLayer_Network_Subnet devolverá un objeto de tipo de datos SoftLayer_Network_Subnet.

Métodos

Un método es una acción específica que puede ejecutarse para un servicio de SLAPI. Cada método devuelve un tipo de datos escalar o estructurado, y puede requerir parámetros, cabeceras o permisos específicos para ejecutarse. Los parámetros de método deben pasarse utilizando las técnicas que se describen en la documentación de cada punto final o lenguaje. En aquellos casos en los que se requieren varios parámetros, páselos en el orden en el que aparecen en la página Método de arriba abajo. La siguiente captura de pantalla muestra los parámetros necesarios para el método SoftLayer_Monitoring_Agent::getGraph. Cuando ejecute este método, pase los parámetros en el orden siguiente: configurationValues, beginDate, endDate.
NOT FOUND: parameters.png
En cada página Método hay disponible una lista completa de parámetros, permisos y cabeceras.

Tipos de datos

Un tipo de datos es una estructura que contiene una colección de valores escalares y otros tipos de datos. Además de valores escalares tradicionales como, por ejemplo, una serie, un booleano o un entero, la SLAPI también utiliza tipos de datos complejos que contienen propiedades que definen los objetos que pasan y devuelven los métodos en la SLAPI. Cada tipo de datos puede contener varias propiedades locales, relacionales y de recuento.

Propiedades locales

Una propiedad local es un hijo directo de un tipo de datos. Las propiedades locales se devuelven normalmente cuando se invoca getObject(). Algunas propiedades locales, si no todas, son necesarias cuando se crea una instancia de este tipo de datos al invocar createObject().

Propiedades relacionales

Una propiedad relacional es un hijo indirecto de un tipo de datos. Las propiedades relacionales se definen en otros tipos de datos o sus propiedades. Por ejemplo, el tipo de datos SoftLayer_Account tiene una propiedad relacional para el hardware. Esta propiedad relacional es una matriz de tipos de datos SoftLayer_Hardware. Cuando se pulsa con una máscara de objeto, esta propiedad devuelve una matriz que contiene un objeto SoftLayer_Hardware para cada dispositivo de hardware en la cuenta.

Propiedades de recuento

Una propiedad de recuento es una propiedad útil que puede utilizarse para determinar el número total de objetos asociados con una propiedad. Por ejemplo, podemos recuperar el número total de VLAN asociados con un determinado servidor utilizando una máscara de objeto con Softlayer_Hardware_Server->networkVlanCount incluido.

Conceptos avanzados de API

Además de las acciones típicas de crear, leer y actualizar, la SLAPI permite a los desarrolladores definir cómo se devuelven los datos desde cada llamada mediante el uso de cabeceras de llamada de API especiales. Estas cabeceras permiten un nivel adicional en el control de la cantidad de datos devueltos por la API.

Límites de resultados

Un límite de resultado es un método de soporte que permite definir un desplazamiento y una cantidad de objetos en la devolución. Esto permite la paginación de grandes conjuntos de datos.

Máscaras de objeto

Una máscara de objeto permite al usuario especificar qué propiedades locales devuelve un método, y recuperar la información encontrada en propiedades relacionales y de recuento. Se crea un mapa o ìmaskî para definir los datos específicos que se van a incluir en el valor de retorno. Por ejemplo, puede recuperar los ID de cada VLAN en un servicio SoftLayer_Hardware_Server especificando una máscara de objeto para ìnetworkVlans.idî al invocar SoftLayer_Hardware_Server::getObject.

Parte del arte de dominar la SLAPI es navegar por las máscaras de objeto para lograr los resultados deseados. Casi siempre hay más de una forma de llegar a un punto de datos específico y algunas pueden ser más eficaces que otras.

Qué camino seguir a partir de aquí

Ahora que conoce los aspectos básicos, es hora de empezar a codificar. Consulte la guía Cómo empezar para ver cómo crear un usuario de API y realizar la primera llamada. También mantenemos varías guías para lenguajes específicos:

Otros enlaces útiles: