Introdução

Este documento descreve como acessar e utilizar as APIs CaTC Northbound (Intent) usando um cliente de API e as ferramentas de desenvolvedor incorporadas da plataforma.

Informações de Apoio

Ele abrange conceitos básicos de HTTP/REST e fornece exemplos práticos para automação e teste.

Pré-requisitos

Requisitos

A Cisco recomenda o conhecimento destes tópicos:

• Protocolos HTTP/1.1 e códigos de status.
• Estilo arquitetônico REST.
• Noções básicas sobre o Cisco Catalyst Center (CaTC)
• Entendimento básico de Bruno (ou clientes API semelhantes, como Postman).

Componentes Utilizados

As informações neste documento são baseadas nas seguintes versões de hardware e software:

• Cisco Catalyst Center versões 2.3.7.x e 3.x
• Bruno versão 4.1.0

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Informações de Apoio

As APIs de Intenção do Catalyst Center permitem que os usuários interajam com o controlador fora da interface gráfica do usuário. Isso permite a automação de fluxos de trabalho personalizados, integração com ferramentas de terceiros e gerenciamento de rede eficiente em escala.

Introdução ao HTTP

O protocolo HTTP é a base da comunicação de dados para a Web. Ele adere a um modelo cliente-servidor em que o cliente envia uma solicitação e o servidor retorna uma resposta.

A solicitação HTTP

Uma solicitação HTTP consiste em quatro partes:

1. Linha de solicitação: Especifica o método (incluindo GET e POST), o URI e a versão do protocolo (como GET /api/v1/nodes HTTP/1.1).
2. Cabeçalhos: Forneça metadados como credenciais de autenticação e tipo de conteúdo.
3. Linha vazia: Separa cabeçalhos do corpo.
4. Corpo da mensagem (opcional): Contém dados enviados ao servidor (comuns em POST/PUT/PATCH).

A Resposta HTTP

Uma resposta HTTP espelha a estrutura da solicitação:

1. Linha de status: Inclui o código de status (como 200 OK).
2. Cabeçalhos: Detalhes sobre o servidor e os dados de resposta.
3. Corpo da mensagem: Os dados reais solicitados (geralmente no formato JSON para o Catalyst Center).

Métodos HTTP (Verbos)

• GET: Recupera dados de um recurso.
• POST: Cria um novo recurso.
• PUT: Substitui um recurso existente.
• CORREÇÃO: Aplica modificações parciais a um recurso.
• DELETE: Remove um recurso.

Códigos de status HTTP

Os códigos de status HTTP são códigos numéricos padronizados retornados por um servidor como parte de uma resposta HTTP. Eles indicam o resultado geral de uma solicitação de cliente e ajudam a entender se a solicitação foi bem-sucedida, requer ação adicional ou encontrou um erro.

Os códigos são agrupados em cinco categorias principais, de acordo com o seu primeiro dígito.

• Os códigos 1xx são informativos e indicam que a solicitação foi recebida e que o processamento continua.
• Os códigos 2xx indicam uma solicitação bem-sucedida, o que significa que o servidor recebeu, entendeu e processou a solicitação com êxito.
• Os códigos 3xx são usados para redirecionamento e indicam que uma ação adicional pode ser necessária para concluir a solicitação.
• Os códigos 4xx representam erros do cliente, o que significa que há um problema com a solicitação enviada pelo cliente.
• Os códigos 5xx representam erros de servidor, o que significa que o servidor encontrou um problema ao tentar processar uma solicitação.

Visão geral do REST

REST (Representational State Transfer) é um estilo arquitetônico para projetar aplicativos em rede. As APIs RESTful usam HTTP como mecanismo de transporte e geralmente usam JSON para troca de dados devido à sua natureza leve.

Quando um cliente interage com uma API REST, o servidor retorna uma representação do estado atual de um recurso. Essa representação é transferida para o cliente como parte da resposta e pode ser expressa em um formato diferente.

REST não é um protocolo. Em vez disso, é um estilo hierárquico que define um conjunto de princípios e restrições para a construção de sistemas distribuídos e APIs. Nas APIs modernas, o JSON é um dos formatos mais comuns porque é leve e fácil de processar.

Uma interação REST típica segue um modelo baseado no cliente (o qual foi mencionado anteriormente no artigo). O cliente envia uma solicitação HTTP usando métodos como GET, POST, PUT, PATCH ou DELETE. O servidor processa e retorna uma resposta HTTP contendo as informações solicitadas ou o resultado da operação.

As APIs RESTful geralmente usam HTTP como o mecanismo de comunicação para executar operações em recursos. Neste modelo, o cliente identifica um recurso/ponto final e usa o método HTTP para indicar a ação a ser executada nesse recurso. Uma API REST pode ser descrita usando vários elementos principais. Primeiro, o URI é usado para identificar o recurso ou ponto de extremidade que o cliente deseja acessar. O URI fornece o local ou o identificador desse recurso dentro da API. Segundo, o cliente usa métodos HTTP padrão, como GET, POST, PUT, PATCH e DELETE para definir a operação de solicitação. Por exemplo, GET pode ser usado para recuperar um recurso, POST para criar um e DELETE para remover um por completo. Finalmente, o recurso é trocado através de uma representação, que é definida por seu tipo de mídia. Essa representação é a forma na qual os dados do recurso são transferidos entre o cliente e o servidor, como JSON ou XML.

APIs Catalyst Center e REST

O CaTC ajuda a simplificar as operações de rede do campus centralizando a automação, a configuração, o gerenciamento de políticas, o monitoramento e a análise. Permite que os administradores de rede implantem e gerenciem dispositivos com mais eficiência, mantenham políticas consistentes, monitorem o comportamento da rede e melhorem a visibilidade operacional geral. Esses recursos podem ser acessados por meio da interface gráfica do usuário (GUI), bem como por meio de APIs e integrações externas.

A plataforma CaTC também fornece APIs que podem ser usadas para criar integrações personalizadas e automatizar operações de rede. Combinando APIs CaTC com soluções Cisco existentes ou aplicativos de terceiros, as organizações podem ampliar a funcionalidade da plataforma e criar fluxos de trabalho personalizados para operações ou requisitos comerciais específicos.

Depois de abordar os conceitos básicos, este documento se concentra nas APIs ascendentes, também chamadas de APIs de intenção, no Cisco Catalyst Center. Essas APIs expõem recursos específicos do Catalyst Center por meio de uma abstração baseada em políticas do objetivo comercial, permitindo que os administradores e desenvolvedores se concentrem no resultado desejado em vez das etapas de configuração individuais necessárias para atingi-lo. 

As APIs Catalyst Center Intent são APIs RESTful que usam o formato de dados JSON para interagir com a plataforma. Eles podem ser usados para descobrir informações de rede, recuperar dados operacionais e executar tarefas de controle e automação suportadas na rede.

Recuperar um token de autenticação usando Bruno

Antes de fazer chamadas à API, você deve se autenticar para receber um token.

1. Identificar o Ponto de Extremidade da API

1. Faça login no Catalyst Center.
2. Navegue até Menu > Plataforma > Developer Toolkit.
3. No menu à esquerda, selecione Authentication > Authentication API.
   
   Kit de Ferramentas do Desenvolvedor do Catalyst Center
   
   
4. Copie a URL (geralmente POST /dna/system/api/v1/auth/token).

2. Configurar Bruno para Autenticação

1. No Bruno, crie uma Nova Solicitação.
2. Defina Type como HTTP e o Method como POST.
   
   Criando uma nova solicitação no Bruno
   
   
3. Insira a URL para a API de autenticação.
   
   Criando uma nova solicitação no Bruno
   
   
4. Navegue até a guia Auth e selecione Basic Auth.
   
   Autenticação Básica para API de Autenticação
   
   
5. Insira suas credenciais do Catalyst Center SUPER ADMIN.
6. Clique em Enviar.
   
   Execução da API de autenticação
   

O servidor retorna um status 200 OK e um payload JSON contendo o Token.

Alternative (Terminal): You can also generate the token by base64-encoding your `username:password` and sending a cURL request or using the **Try** button in the Catalyst Center GUI to copy the generated token.

Obtendo a codificação base64 para o nome de usuário e a senha

Inserindo Autenticação Básica com nome de usuário e senha base64 codificados

Obtendo o token de autenticação da GUI do Catalyst Center.

Neste ponto, você tem o Token de Autenticação, na resposta Bruno ou na resposta do Catalyst Center Developer Toolkit. 

Agora adicione o token como um Cabeçalho nas configurações da coleção no Bruno, isso facilita qualquer outra solicitação criada dentro da coleção para usar o token, de modo que você não tenha necessidade de inserir o token manualmente como um cabeçalho para cada solicitação.

3. Defina um Cabeçalho Global no Bruno

Para evitar a reautenticação para cada solicitação, defina o token como um cabeçalho em nível de coleção:

1. Clique com o botão direito do mouse em sua coleção e selecione Configurações.
   
   Configurações da Coleção
   
   
2. Vá até a guia Cabeçalhos.
3. Adicionar um novo cabeçalho:
   • Nome: x-auth-token
   • Valor: [Cole seu token aqui]
     
     Inserindo cabeçalhos globais para a Coleção de API no Bruno.
     
4. Click Save.

Neste ponto, você gerou o token de autenticação para fazer qualquer outra solicitação de API do Catalyst Center. 

Exemplo 1: Criar um andar do site

Este exemplo demonstra como criar um andar dentro da hierarquia de rede (Global > TestArea > TestBuilding).

Hierarquia de rede

Passo 1: Obter a ID do Pai

Use a API GET /dna/intent/api/v1/sites para localizar a ID de TestBuilding.

• Parâmetro de consulta: nameHierarchy=Global/TestArea/TestBuilding
• Copiar o ID da resposta; esta é sua parentId.

Solicitação GET para /dna/intent/api/v1/sites?nameHierarchy=Global/TestArea/TestBuilding

Passo 2: Criar a tribuna

1. Crie uma solicitação de POST para /dna/intent/api/v2/floor.
2. Na guia Corpo (JSON), informe os parâmetros necessários:

{
  "name": "Floor 1",
  "parentId": "your-building-id-here",
  "floorNumber": 1,
  "rfModel": "Cubic-Office",
  "width": 100,
  "length": 100,
  "height": 10,
  "unitsOfMeasure": "feet"
}

3. Clique em Enviar. Uma resposta bem-sucedida confirma a criação da tribuna.

Solicitação POST para criar a tribuna

API GET para validar a criação de chão de fábrica através de uma solicitação POST.

Finalmente, para validar se a tribuna foi criada com êxito, você pode executar a API anterior e modificar a consulta para corresponder ao caminho hierárquico completo, como mostrado acima. 

Exemplo 2: Recuperar informações de interface

Este exemplo mostra como obter o status de uma interface específica em um dispositivo de rede.

Passo 1: Identificar a ID do dispositivo

Na GUI do Catalyst Center, vá para Inventory, clique no seu dispositivo e veja o URL no seu navegador. O último segmento é a ID do dispositivo.

Passo 2: Crie uma solicitação parametrizada no Bruno

1. Crie uma solicitação GET para /dna/intent/api/v1/interface/network-device/{{deviceId}}.
2. Na guia Vars da solicitação, adicione uma variável chamada deviceId e cole sua ID.
3. Para filtrar uma porta específica, adicione um Parâmetro de consulta:
   • Chave: nome
   • Valor: GigabitEthernet1/0/5
     
     Criando variáveis no Bruno
     
     
4. Clique em Enviar.

Solicitação GET aplicando uma consulta

Conclusão

As APIs ascendentes do Catalyst Center fornecem flexibilidade poderosa para administradores de rede. Ao fazer a transição do gerenciamento baseado em GUI para fluxos de trabalho orientados por API, você pode automatizar tarefas repetitivas, garantir a consistência da configuração e integrar a inteligência de rede em seu ecossistema de TI mais amplo.

Histórico de revisões

Revisão	Data de publicação	Comentários
1.0	14-Oct-2026	Versão inicial