REST

O SoftLayer fornece uma API RESTful além dos serviços da API estilo RPC. Use a API REST em casos em que sua linguagem de programação pode não ter suporte a SOAP ou XML-RPC, mas pode executar ações simples do protocolo HTTP e pode interpretar dados XML ou JSON.

URLs de REST

URLs de API REST são estruturadas para atravessar facilmente a hierarquia de objeto da SoftLayer. Uma solicitação REST básica é estruturada da seguinte forma:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • Todas as solicitações REST, até mesmo as solicitações de rede privada, devem ser passadas por meio de SSL HTTP.
  • Use o nome do usuário e a chave da API para autenticar a solicitação por meio de autenticação HTTP.
  • O nome do host base e o nome da pasta para uma solicitação REST é api.softlayer.com/rest/v3/ ou api.service.softlayer.com/rest/v3/. Use api.service.softlayer.com/rest/v3/ para acessar a API REST pela rede privada da SoftLayer. É uma maneira mais segura de se comunicar com a SoftLayer, mas o sistema que está fazendo as chamadas de API deve estar na rede privada da SoftLayer (comprada da SoftLayer ou com login efetuado na VPN da rede privada da SoftLayer).
  • Siga a URL base com o nome do serviço da API que deseja chamar, por exemplo, "SoftLayer_Account" ou "SoftLayer_Hardware_Server".
  • Se a solicitação da API precisar de um parâmetro de inicialização, então, inclua uma barra seguida pelo ID do parâmetro de inicialização para a URL.
  • A API da SoftLayer REST pode retornar a saída XML ou JSON formatada. Inclua ".xml" ou ".json" no fim da solicitação para especificar em qual formato você gostaria de receber dados.

Uma solicitação como essa chama o método getObject() do serviço da API que você está tentando chamar. SoftLayer_Account::getObject não requer um parâmetro de inicialização, portanto, sua URL de REST tem a aparência a seguir:

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

No entanto, para chamar o método getObject() para um registro SoftLayer_Hardware_Server específico, use a URL a seguir, supondo que "1234" seja o ID do servidor que você deseja recuperar:

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

Chame métodos da API, diferentes de getObject(), colocando o nome do método após o parâmetro de inicialização. Se seu método iniciar com "get", então, remova a palavra "get" do nome do método e converta sua primeira letra para maiúscula. Esse método também pode ser usado para acessar rapidamente as propriedades relacionais de um objeto. Por exemplo, o método getHardware() e a propriedade relacional hardware no serviço da API SoftLayer_Account podem ser atingidos em:

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

De forma semelhante, os componentes de rede de um servidor podem ser atingidos na URL a seguir:

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

Encadeie uma combinação de IDs de parâmetros de inicialização e propriedades relacionais para realizar drill down em componentes de objetos específicos. Cada ID incluído irá fazer drill down naquela propriedade relacional específica. Por exemplo, se desejar obter o componente de rede do servidor 1234 com ID 5678 use a URL:

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

E para obter a conexão uplink do componente de rede:

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

Tipos de solicitações de HTTP

DELETE

Use uma solicitação de HTTP DELETE para excluir um objeto, em vez do método deleteObject() de um serviço. Por exemplo, passe uma solicitação de HTTP DELETE à URL a seguir para remover o registro do domínio 1234 dos servidores DNS da SoftLayer.

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

GET

Use as solicitações de HTTP GET para chamadas simples de método e de recuperação de objeto. Por exemplo, recupere o ID de registro do domínio 1234 com uma solicitação de HTTP GET para a URL:

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

POST

Use uma solicitação de HTTP POST para criar um objeto, em vez dos métodos createObject() ou createObjects() de
um serviço. Efetue POST de uma única estrutura JSON ou XML que contém um único elemento chamado "parameters" contendo a estrutura básica do objeto e quaisquer outros
parâmetros necessários para o método createObject() do serviço da API. Por exemplo, passe uma solicitação de HTTP POST com os dados à URL a seguir para
criar um registro de domínio nos servidores DNS da 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

Use uma solicitação de HTTP PUT para editar um objeto, em vez dos métodos editObject() ou editObjects() de um serviço. Efetue PUT de uma única estrutura JSON ou XML que contém um único elemento chamado "parameters" contendo a estrutura básica do objeto e quaisquer outros parâmetros necessários para o método editObject() do serviço da API. Por exemplo, passe uma solicitação de HTTP PUT com os dados a seguir à URL a seguir para editar o registro do recurso de domínio 5678 no registro do domínio 1234 nos servidores DNS da SoftLayer, alterando data para "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

Passando parâmetros de métodos

Parâmetros são passados em nossa API REST anexando cada um ao caminho da URL.
Eles devem ser passados na mesma ordem que são listados na documentação de cada método, de cima para baixo.

Por exemplo, SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber requer o parâmetro userRecordId:

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

Alguns métodos irão solicitar um único parâmetro que é uma matriz, como 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"}
      ]
    ]
}

Maneiras alternativas para configurar formatos de parâmetros e de retorno

Além de incluir ".json" e ".xml" em sua URL de REST, também é possível configurar formatos de retorno de chamada API passando um tipo MIME (application/json para JSON e text/xml para XML) nos cabeçalhos HTTP Accept ou Content-Type em sua solicitação.

Usando máscaras de objetos

Crie uma máscara de objeto na URL da chamada API incluindo uma variável objectMask na sequência de consultas. As máscaras de objetos são uma lista de propriedades relacionais delineadas por um ponto-e-vírgula, com propriedades relacionais encadeadas separadas por pontos. Para economizar espaço na sequência de consultas, as máscaras de objetos REST são relativas ao tipo de dados do fim da URL, em vez do serviço da API que você está consultando. De forma semelhante, as máscaras de objetos REST não contêm uma propriedade mask.

A URL a seguir cria uma máscara de objeto que recupera os registros de hardware de uma conta com os datacenters nos quais o hardware está localizado. Observe que a máscara de objeto contém somente a propriedade relacional que desejamos recuperar relacionada a hardware, não nossa conta.

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

Essa URL obtém os registros de hardware de uma conta com os registros associados do datacenter, do sistema operacional e dos componentes de rede do hardware. Observe que esses itens relacionais são separados por ponto-e-vírgula.

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

Essa URL obtém os registros de hardware de uma conta com os registros associados do datacenter, do sistema operacional, da senha do sistema operacional e dos componentes de rede do hardware. Propriedades relacionais encadeadas são separadas por pontos.

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

A API REST pode manipular máscaras de objetos de maneira ligeiramente diferente do que as API da SoftLayers SOAP e XML-RPC. As máscaras de objetos REST podem ser feitas para filtrar propriedades de tipos de dados locais recuperadas da API da SoftLayer. Se você definir uma propriedade local na máscara, então, a API da SoftLayer trata a máscara como um filtro e irá recuperar somente as propriedades locais especificadas na máscara. Por exemplo, esta URL recupera somente as propriedades id e hostname nos registros de hardware de uma conta:

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

Usando limites de resultados

Limite o número de resultados em uma chamada API incluindo uma variável resultLimit na sequência de consultas. Configure a variável resultLimit para um conjunto de dois números delineado por vírgula:

  • O deslocamento no qual iniciar o conjunto de resultados.
  • O número de resultados ao qual limitar sua chamada.

Essa URL recupera os dois primeiros chamados abertos em uma conta, chamando o método SoftLayer_Account::getOpenTickets:

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

Manipulação de erros

A API da SoftLayer REST retorna saída XML ou JSON com um único nó error contendo quaisquer mensagens de erro retornadas pela chamada API. Por exemplo, a URL para o serviço nonexistent:
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
retorna o erro:

>
   Service does not exist>
>

Enquanto que o equivalente em JSON:

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

retorna o erro:

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

Erros de autenticação

A API da SoftLayer REST retorna um erro de HTTP 401 Desautorizado se uma combinação inválida de nome do usuário/chave da API for usada ao solicitar uma URL de REST.

Advertências

Especificando tipos complexos

Como com XML-RPC, a API REST não pode determinar tipos complexos estendidos em determinados parâmetros. Nesses casos, você deve definir uma propriedade complexType nos parâmetros complexos configurados para o tipo de objeto que está enviando ao método.

Componentes da API referidos

Serviços

Tipos de dados

Métodos