REST APIs para Automação de Redes

O que é

Uma API (Application Programming Interface) é uma interface de software que permite que dois programas se comuniquem entre si. No mundo das redes, APIs são o mecanismo pelo qual sistemas de automação acessam e modificam dispositivos sem intervenção humana no CLI.

REST — Representational State Transfer — não é um protocolo. É uma arquitetura: um conjunto de seis regras que define como uma API deve funcionar. Uma API que segue essas regras é chamada de RESTful. O protocolo de transporte mais comum é o HTTP ou, em produção, sempre o HTTPS.

REST vs SOAP

SOAP foi o padrão dominante nos anos 2000. Hoje, novos projetos de automação de redes — inclusive os da Cisco — adotam REST. Para o CCNA, entenda REST como o padrão do mercado e SOAP como tecnologia legada.

Os 6 princípios da arquitetura REST

A especificação original define seis restrições. Para o CCNA, foque nas três marcadas com ★:

Como funciona

CRUD: as quatro operações

Toda interação com uma API REST gira em torno de quatro operações chamadas CRUD:

Verbos HTTP e mapeamento CRUD

O HTTP usa métodos (verbos) que mapeiam diretamente para as operações CRUD:

PUT vs PATCH: PUT envia a configuração completa do recurso e substitui tudo. PATCH envia apenas os campos alterados. Se você quiser mudar somente o IP de uma interface sem tocar no restante da configuração, use PATCH.

Estrutura de uma requisição REST

Quando um cliente REST faz uma chamada, o pacote HTTP contém:

1. Verbo HTTP — define a operação (GET, POST, etc.)
2. URI — endereço do recurso a ser acessado
3. Headers — metadados: tipo de dado aceito (Accept: application/json), token de autenticação (Authorization), tipo do body (Content-Type: application/json)
4. Body — dados enviados ao servidor (usado em POST, PUT, PATCH)

Anatomia de uma URI:

https://10.10.20.85/restconf/data/ietf-interfaces:interfaces
 ^^^^^  ^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Scheme   Authority              Path (recurso)

• Scheme: protocolo — http ou https
• Authority: endereço do servidor (IP ou hostname)
• Path: recurso que você quer acessar

JSON como formato de dados

REST APIs usam JSON (JavaScript Object Notation) como formato principal, embora XML também seja suportado. JSON é preferido por ser mais compacto e legível. A estrutura chave-valor do JSON é facilmente processada por Python, JavaScript e outras linguagens de automação.

Exemplo de resposta JSON de um roteador Cisco IOS-XE via RESTCONF:

{
  "ietf-interfaces:interface": {
    "name": "GigabitEthernet1",
    "description": "Link para SP - São Paulo",
    "type": "iana-if-type:ethernetCsmacd",
    "enabled": true,
    "ietf-ip:ipv4": {
      "address": [
        {
          "ip": "200.10.50.1",
          "prefix-length": 30
        }
      ]
    }
  }
}

Autenticação

APIs REST exigem autenticação para proteger o acesso a dados e configurações:

Em produção, sempre use HTTPS. Sem criptografia, qualquer método de autenticação é vulnerável a interceptação.

Códigos de resposta HTTP

O servidor responde com um código de 3 dígitos. O primeiro dígito indica a classe:

Códigos que aparecem no exame CCNA:

Na prática

Exemplo 1 — Cisco Catalyst Center (ex-DNA Center)

O Catalyst Center é o controlador SDN da Cisco. Sua API REST é usada na interface northbound para automação de rede.

Etapa 1 — Autenticar e obter token (POST com Basic Auth):

POST https://sandboxdnac.cisco.com/dna/system/api/v1/auth/token
Authorization: Basic <base64 de usuário:senha>
Content-Type: application/json

Resposta 201 Created:

{
  "Token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Etapa 2 — Consultar inventário (GET com token):

GET https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device
X-Auth-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Resposta 200 OK com lista de dispositivos em JSON.

Exemplo 2 — RESTCONF no Cisco IOS-XE

O IOS-XE suporta RESTCONF nativamente (RFC 8040). Permite consultar e modificar configurações via API REST diretamente no roteador.

Consultar interfaces (GET com Basic Auth):

GET https://10.10.20.85/restconf/data/ietf-interfaces:interfaces
Authorization: Basic <base64 de admin:senha>
Accept: application/yang-data+json

Alterar descrição de interface (PATCH):

PATCH https://10.10.20.85/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
Authorization: Basic <base64>
Content-Type: application/yang-data+json

{
  "ietf-interfaces:interface": {
    "name": "GigabitEthernet1",
    "description": "Uplink ISP - São Paulo"
  }
}

Resposta 204 No Content indica sucesso sem body de retorno.

Por que cai no exame

O tópico 6.5 do CCNA 200-301 exige que você descreva as características das REST APIs. Questões frequentes:

• Mapeamento CRUD ↔ verbo HTTP: POST=Create, GET=Read, PUT/PATCH=Update, DELETE=Delete. Memorize a tabela.
• Stateless é uma restrição REST: cada requisição é independente. O servidor não guarda sessão. Não confunda com o TCP subjacente (que é stateful) — camadas diferentes têm comportamentos diferentes.
• Código 404 vs 401 vs 403: 404 = recurso não encontrado; 401 = não autenticado; 403 = autenticado mas sem permissão.
• REST vs SOAP: REST usa JSON/XML, é leve e stateless. SOAP usa só XML, é mais verboso e pode ser stateful.
• Northbound vs Southbound SDN: REST APIs são usadas na interface northbound (apps ↔ controlador). RESTCONF e NETCONF são southbound (controlador ↔ dispositivos).
• URI: composta por scheme (protocolo), authority (host/IP) e path (recurso).
• PUT vs PATCH: PUT substitui tudo; PATCH altera apenas os campos enviados.

Resumo em uma linha

REST APIs permitem que programas acessem e modifiquem recursos de rede via HTTP com verbos padronizados (GET/POST/PUT/PATCH/DELETE), dados em JSON e comunicação stateless — base da automação SDN moderna.