Executando comandos REST

Muitos programas diferentes podem executar comandos REST. Para executar o comando, você chama um método em um recurso REST e transmite parâmetros ou uma solicitação no formato JSON.
Nota: O uso de comandos REST requer as mesmas permissões que o uso da interface da web. Para obter informações sobre permissões, consulte Roles and permissions.

Exemplo: Executando comandos REST simples com curl

O programa curl do Linux é uma maneira simples de executar comandos REST. Para executar um comando REST, junte a URL de um dos recursos REST, especifique o método a ser usado e inclua quaisquer parâmetros. Por exemplo, o comando curl a seguir recupera uma lista de todos os componentes ativos. O comando chama o método GET do recurso component e transmite o valor true para o parâmetro active:
curl -k -u admin:admin 
  https://hostname:port/cli/component?active=true 
  -X GET
Nota: Deve-se inserir este comando em uma única linha. Ele é dividido em linhas diferentes aqui para maior clareza.
Nota: Este exemplo usa o comutador -k para se conectar ao servidor de forma insegura. Para configurar a autenticação, consulte Autenticando para comandos REST.
Use o nome do host e a porta do servidor para hostname e port. Por exemplo, se o nome do host for ucdeploy.example.org e a porta for o valor padrão de 8443, o comando curl poderá ser semelhante ao seguinte exemplo:
curl -k -u admin:admin 
  https://ucdeploy.example.org:8443/cli/component?active=true 
  -X GET
A resposta para esse comando é uma lista JSONArray de todos os componentes ativos no servidor. Para obter um exemplo dessa resposta, consulte Get information about all components on the server.

Transmitindo parâmetros para comandos REST

Muitos comandos REST têm um ou mais parâmetros. Para transmitir estes parâmetros, inclua-os na URL. Por exemplo, o método GET do comando version/getLink obtém três parâmetros: o nome ou ID do aplicativo, o nome ou ID da versão e o nome do link. Para obter um link no componente JPetStore-APP, o comando pode ser semelhante ao exemplo a seguir:
curl -k -u admin:admin 
  "https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/
  version/getLink?component=JPetStore-APP
  &version=1.0
  &linkName=IBM%20web%20site"
Nesse caso, cada parâmetro e par de valores são anexados à URL, após um ponto de interrogação (?). Um e comercial (&) separa cada par. Como curl é um comando Linux e o e comercial possui um significado especial na linha de comandos do Linux, a URL, incluindo os parâmetros, é colocada entre aspas.
Nota: Todos os valores de parâmetro devem ser codificados por URL. O exemplo anterior transmitiu o valor IBM web site como o valor para o parâmetro linkName. Para incluir esse parâmetro como parte da URL, os espaços devem ser alterados para o valor codificado por URL %20.

Transmitindo sequências JSON para comandos

Para comandos mais complexos, deve-se enviar uma sequência JSON ou arquivo em vez de ou além dos parâmetros.
Por exemplo, o método PUT do recurso application/create cria um aplicativo. Para usar esse comando, deve-se transmitir uma sequência JSON que especifica o nome, a descrição e algumas propriedades do novo aplicativo. A sequência JSON para este comando deve seguir este modelo:
{
  "description": "Description",
  "enforceCompleteSnapshots": "Specify true to require 
     an explicit version for each component",
  "name": "Application name or ID",
  "notificationScheme": "Notification scheme"
}
Este modelo é listado nas informações de referência para o comando; consulte Create an application from a JSON file.
Por exemplo, a sequência JSON a seguir representa um aplicativo que é denominado MyApplication:
{
  "description": "My new application",
  "enforceCompleteSnapshots": "false",
  "name": "My Application",
  "notificationScheme": "Default Notification Scheme"
}
Para transmitir esta sequência JSON ao recurso application/create, é possível salvar a sequência em um arquivo ou incluí-la no comando. Por exemplo, se você salvar a sequência em um arquivo que é denominado newApplication.json, o comando será semelhante ao exemplo a seguir:
curl -k -u admin:admin 
  https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create 
  -X PUT -d @newApplication.json
Também é possível transmitir a sequência diretamente para o comando, conforme mostrado no exemplo a seguir:
curl -k -u admin:admin 
  https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create 
  -X PUT 
  -d {"description":"My new application",
      "enforceCompleteSnapshots":"false",
      "name":"My Application 67",
      "notificationScheme":"Default Notification Scheme"}

Compondo sequências JSON

Há duas maneiras principais para obter o modelo da sequência JSON para um comando. Os modelos são listados nas informações de referência para cada comando. Também é possível executar o comando do cliente da linha de comandos equivalente com a opção -t. A execução do comando da CLI com essa opção imprime o modelo JSON.

Como a interface do servidor usa a API REST, também é possível efetuar login no servidor como de costume e monitorar as solicitações que o aplicativo da web gera. É possível monitorar essas solicitações com extensões do navegador da web ou programas externos. Por exemplo, para ver a sequência JSON para o método PUT do recurso resource/create, crie um recurso no servidor da web como de costume e, em seguida, consulte a sequência JSON na solicitação do navegador, conforme mostrado na figura a seguir. A sequência JSON para os comandos REST é igual ou semelhante a esta sequência.

Usando uma extensão do navegador da web para monitorar as sequências JSON que o servidor usa

Respostas

Após um comando bem-sucedido, a maioria dos comandos retorna um valor da sequência de caracteres simples ou uma sequência JSON.
Além do resultado do comando, os comandos retornam códigos de status de HTTP padrão. A lista a seguir inclui os códigos de status mais comuns que os comandos REST retornam.
200
O comando foi bem-sucedido.
400
  • Você não tem permissão para executar o comando.
  • Você não especificou um parâmetro necessário.
  • O caminho do recurso na URL está incorreto.
404
O objeto que você está tentando recuperar não existe.
405
O nome do método de HTTP está incorreto.
415
O tipo de conteúdo no cabeçalho da solicitação está incorreto.
500
O servidor encontrou um erro.

Feedback