Guia da API v3 SUSE Rancher Prime anterior

A API v3 anterior possui sua própria interface de usuário acessível a partir de um navegador web. Esta é uma maneira fácil de ver recursos, realizar ações e ver a equivalente curl ou a solicitação e resposta HTTP. Para acessá-la:

As solicitações de API devem incluir informações de autenticação. A autenticação é feita com autenticação básica HTTP usando rancher-admin/users/settings/api-keys.adoc[chaves de API]. As chaves de API podem criar novos clusters e têm acesso a múltiplos clusters via /v3/clusters/. Funções de cluster e projeto se aplicam a essas chaves e restringem quais clusters e projetos a conta pode ver e quais ações pode realizar.

Por padrão, certos tokens de API em nível de cluster são gerados com tempo de vida infinito (ttl=0). Em outras palavras, tokens de API com ttl=0 nunca expiram, a menos que você os invalide. Para detalhes sobre como invalidá-los, consulte a página de tokens de API.

A API é geralmente RESTful, mas possui vários recursos para tornar a definição de tudo descobrível por um cliente, de modo que clientes genéricos possam ser escritos em vez de ter que escrever código específico para cada tipo de recurso. Para informações detalhadas sobre a especificação genérica da API, veja a documentação adicional.

O design permite que você carregue apenas a lista de esquemas e acesse tudo sobre a API. A interface do usuário da API não contém código específico do Rancher em si. A URL para obter Esquemas é enviada em cada resposta HTTP como um cabeçalho X-Api-Schemas. A partir daí, você pode seguir o collection link em cada esquema para saber onde listar recursos e seguir outros links dentro dos recursos retornados para obter qualquer outra informação.

Na prática, você pode querer apenas construir strings de URL. Recomendamos fortemente limitar isso ao nível superior para listar uma coleção (/v3/<type>) ou obter um recurso específico (/v3/<type>/<id>). Qualquer coisa mais profunda do que isso está sujeita a mudanças em futuras versões.

Os recursos têm relacionamentos entre si chamados links. Cada recurso inclui um mapa de links com o nome do link e a URL onde você pode recuperar essa informação. Novamente, você deve GET o recurso e, em seguida, seguir a URL no mapa links, não construir essas strings você mesmo.

A maioria dos recursos tem ações, que fazem algo ou mudam o estado do recurso. Para usá-las, envie um HTTP POST para a URL no mapa actions da ação que você deseja. Certas ações requerem entrada ou produzem saída. Consulte a documentação individual para cada tipo ou os esquemas para informações específicas.

Para editar um recurso, envie um HTTP PUT para o link links.update no recurso com os campos que você deseja alterar. Se o link estiver ausente, então você não tem permissão para atualizar o recurso. Campos desconhecidos e aqueles que não são editáveis são ignorados.

Para deletar um recurso, envie um HTTP DELETE para o link links.remove no recurso. Se o link estiver ausente, então você não tem permissão para atualizar o recurso.

Para criar um novo recurso, envie um HTTP POST para a URL da coleção no esquema (que é /v3/<type>).

A maioria das coleções pode ser filtrada no lado do servidor por campos comuns usando parâmetros de consulta HTTP. O mapa filters mostra quais campos podem ser filtrados e quais foram os valores filtrados para a solicitação que você fez. A interface da API possui controles para configurar a filtragem e mostrar a solicitação apropriada. Para correspondências simples de "igual", é apenas field=value. Modificadores podem ser adicionados ao nome do campo, por exemplo, field_gt=42 para "campo é maior que 42." Consulte a especificação da API para detalhes completos.

A maioria das coleções pode ser ordenada no lado do servidor por campos comuns usando parâmetros de consulta HTTP. O mapa sortLinks mostra quais ordenações estão disponíveis, junto com a URL para obter a coleção ordenada por isso. Ele também inclui informações sobre como a resposta atual foi ordenada, se especificado.

As respostas da API são paginadas com um limite de 100 recursos por página por padrão. Isso pode ser alterado com o parâmetro de consulta limit, até um máximo de 1000, por exemplo, /v3/pods?limit=1000. O mapa pagination nas respostas da coleção informa se você possui ou não o conjunto completo de resultados e tem um link para a próxima página, se você não tiver.

Você pode usar as ferramentas de desenvolvedor do navegador para capturar como a API v3 é chamada. Por exemplo, você pode seguir estas etapas para usar as ferramentas de desenvolvedor do Chrome para obter a chamada da API para provisionar um cluster de distribuição Kubernetes do Rancher: