Visão geral da API SoftLayer

A interface de programação de aplicativos (API) SoftLayer é a interface de desenvolvimento que fornece aos desenvolvedores e administradores do sistema interação direta com o sistema de backend da SoftLayer. A funcionalidade exposta por nossa API permite que usuários executem gerenciador de servidor remoto, monitoramento e recuperem informações de vários sistemas da SoftLayer, como de contabilidade, inventário e DNS. Nossa API confere poderes a muitos dos recursos do Portal do cliente SoftLayer, o que geralmente significa que se uma interação for possível no Portal do cliente, poderá ser executada em nossa API também.

Quem deve usar a API?

A API da SoftLayer (SLAPI) está disponível a todos os clientes da SoftLayer sem encargo adicional. Incentivamos nossos clientes com um conhecimento básico de programação orientada a objetos a tomarem total proveito dos recursos que a SLAPI oferece. Embora clientes da SoftLayer usem a SLAPI para diversas tarefas, a capacidade de interagir programaticamente com todas as partes do ambiente da SoftLayer dentro da API resulta em a maioria de nossos clientes usar a SLAPI para automatizar tarefas.

Usando a API da SoftLayer

Antes de iniciar

A SLAPI fornece aos usuários interação direta com os objetos que executam o Portal do Cliente. Antes de desenvolver para a SLAPI, é incrivelmente benéfico entender os conceitos de programação básica orientada a objetos, como objetos, propriedades, métodos e herança. Os métodos da SLAPI são executados com relação a objetos de serviço em nossos sistemas de backend, que retornam objetos de tipos de dados específicos da SoftLayer e tipos de dados padrão, como números inteiros, booleanos e sequências.
A SLAPI é um sistema de Chamada de procedimento remoto. Cada chamada envolve enviar dados para um terminal de API e receber dados estruturados em retorno. O formato usado para enviar e receber dados com a SLAPI depende de qual implementação da API você escolher. A SLAPI atualmente usa SOAP, XML-RPC ou REST para transmissão de dados. Antes de fazer chamadas de API, é útil entender como usar esses protocolos em sua linguagem de programação ou de script. É possível usar qualquer uma das implementações em seu aplicativo. Também fornecemos diversos clientes da API específicos de serviços disponíveis em várias de nossas linguagens suportadas em nosso perfil do github.

Criando um usuário da API

Toda chamada à SLAPI é autenticada por uma conta do Portal do cliente. As contas no Portal do cliente podem conter diversos usuários e é altamente recomendável criar um usuário exclusivo do Portal do cliente para executar chamadas de API. Independentemente de se você está desenvolvendo um aplicativo ou usando um aplicativo baseado em API desenvolvido por outros, deve-se autenticar dentro do programa para acessar informações e interagir com quaisquer aspectos de sua conta. Autenticação na SLAPI requer o nome do usuário do Portal do cliente e a chave da API, um token de autenticação especial reservado para chamadas de método da API. Permissões de usuário definidas no Portal do cliente são refletidas nas chamadas de API.

Escolhendo a rede pública ou privada

Servidores de terminais da SLAPI existem nas redes pública e privada da SoftLayer. Seus aplicativos baseados na API podem se conectar a partir de qualquer host na Internet; no entanto, a rede privada da SoftLayer oferece uma camada adicional de segurança de dados. Além disso, a SoftLayer oferece diversos terminais de API de rede privada, que estão acessíveis somente quando conectados à rede privada. Todos os servidores e instâncias de computação associados a uma conta SoftLayer têm uma conexão direta com a rede privada e não requerem autenticação adicional. Se desejar usar terminais privados a partir de outro dispositivo, uma conexão de VPN para nossa rede privada será necessária.

Conceitos básicos de API

Serviços

Um serviço é um terminal associado a sistemas internos da SoftLayer. Cada serviço é uma coleção de métodos, ou ações, que podem ser executados. Uma lista de todos os serviços da SLAPI pode ser localizada na seção Referência deste site.
Ao acessar a seção Serviços para a API desejada, uma lista de todos os serviços disponíveis é exibida do lado esquerdo da tela. Todos os serviços da SoftLayer iniciam com "SoftLayer_" e contêm termos adicionais que definem a função geral que o serviço fornece: "Hardware", "Account", "Billing", "Network", etc. Cada serviço é estendido daí com um nome que define a função específica do serviço dentro daquele subconjunto específico. Cada serviço associado à API da SoftLayer tem um nome exclusivo. Embora alguns serviços, como SoftLayer_Account e SoftLayer_Account_Address, possam compartilhar um prefixo comum, a interação dos mesmos não é necessariamente semelhante e não há nenhuma herança direta para serviços com nome semelhante. Devido a isso, cada serviço deve ser abordado individualmente.
Para visualizar detalhes de um serviço específico, clique no nome do serviço. A página de cada serviço inclui uma lista de métodos disponível para aquele serviço e muitas também incluem uma breve visão geral para explicar o serviço. Embora cada serviço ofereça um conjunto exclusivo de métodos, muitos serviços oferecem o método getObject. Esses métodos podem ser usados para recuperar um objeto do mesmo tipo da API. Por exemplo, chamar o método getObject no serviço SoftLayer_Network_Subnet retornará um objeto de tipo de dados SoftLayer_Network_Subnet.

Métodos

Um método é uma ação específica que pode ser executada para um serviço da SLAPI. Cada método retorna um tipo de dado escalar ou estruturado e pode requerer parâmetros, permissões ou cabeçalhos específicos para execução. Os parâmetros dos métodos devem ser passados usando as técnicas descritas na documentação de cada linguagem ou terminal. Em situações em que diversos parâmetros são necessários, passe os parâmetros na ordem que aparecem na página Método de cima para baixo. A captura de tela abaixo exibe os parâmetros necessários para o método SoftLayer_Monitoring_Agent::getGraph. Ao executar esse método, passe os parâmetros na ordem a seguir: configurationValues, beginDate, endDate.
NOT FOUND: parameters.png
Uma lista completa de parâmetros, permissões e cabeçalhos está disponível na página de cada Método.

Tipos de dados

Um tipo de dados é uma estrutura que contém uma coleção de valores escalares e outros tipos de dados. Além de valores escalares tradicionais, como string, bool ou int, a SLAPI também usa tipos de dados complexos que contêm propriedades que definem os objetos passados aos métodos e retornados pelos mesmos na SLAPI. Cada tipo de dados contém potencialmente diversas propriedades locais, relacionais e de contagem.

Propriedades locais

Uma propriedade local é um filho direto de um tipo de dado. As propriedades locais geralmente são retornadas quando getObject() é chamado. Algumas, se não todas, propriedades locais são necessárias na criação de uma instância desse tipo de dados ao chamar createObject().

Propriedades relacionais

Uma propriedade relacional é um filho indireto de um tipo de dado. As propriedades relacionais são definidas em outros tipos de dados ou suas propriedades. Por exemplo, o tipo de dados SoftLayer_Account tem uma propriedade relacional para hardware. Essa propriedade relacional é uma matriz de tipos de dados SoftLayer_Hardware. Quando tocada com uma máscara de objeto, essa propriedade retornará uma matriz que contém um objeto SoftLayer_Hardware para cada dispositivo de hardware na conta.

Propriedades de contagem

Uma propriedade de contagem é uma propriedade de conveniência que pode ser usada para determinar o número total de objetos associado a uma propriedade. Por exemplo, poderíamos recuperar o número total de VLANs associadas a um servidor específico usando uma máscara de objeto com Softlayer_Hardware_Server->networkVlanCount incluído.

Conceitos avançados de API

Além das ações típicas de criar, ler, atualizar e excluir, a SLAPI permite que desenvolvedores definam como dados são retornados de cada chamada por meio do uso de cabeçalhos especiais de chamada API. Esses cabeçalhos permitem um nível adicional de controle sobre a quantia de dados retornados pela API.

Limites de resultados

Um limite de resultado é um método de suporte que permite definir um deslocamento e a quantia de objetos a retornar. Isso permite a paginação de grandes conjuntos de dados.

Máscaras de objetos

Uma máscara de objeto permite que o usuário especifique quais propriedades locais retornar de um método e recupere informações localizadas em propriedades relacionais e de contagem. Um mapa, ou ìmaskî, é criado para definir os dados específicos a serem incluídos no valor de retorno. Por exemplo, é possível reunir os IDs de cada VLAN em um SoftLayer_Hardware_Server especificando uma máscara de objeto para ìnetworkVlans.idî ao chamar SoftLayer_Hardware_Server::getObject.

Parte da arte de dominar a SLAPI é navegar pelas máscaras de objetos para atingir os resultados desejados. Mais frequentemente do que não, há mais de uma maneira de chegar a um ponto de dados específico e algumas podem ser mais eficientes do que outras.

Para onde ir daqui

Agora que você conhece o básico, chegou a hora de iniciar a codificação. Consulte nosso Guia de introdução para ver como criar um usuário de API e fazer sua primeira chamada. Também mantemos diversos guias para linguagens específicas:

Outros links úteis: