Introdução à API REST

Conteúdo da lição

• Configuração

o Roteador

o Python

▪ Interface GET

▪ Interface PUT

• Conclusão

Nesta lição, vamos dar uma olhada no que é uma API REST. Primeiramente, o que
é uma API?

Nós, como engenheiros de rede, geralmente usamos a interface de linha de

comando (CLI) ou uma interface gráfica de usuário (GUI) para configurar ou
monitorar nossos dispositivos de rede. Analisar comandos de exibição e
depuração com scripts é difícil porque esses comandos são destinados a
humanos. Para interagir com aplicativos ou dispositivos de rede, podemos usar
uma Interface de Programação de Aplicativos (API).

Uma API é uma interface de software que permite que outros aplicativos se
comuniquem com o nosso aplicativo.

Roy T. Fielding descreve o REST em sua dissertação (capítulo 5) . É uma sigla para
Transferência de Estado Representacional (RE presentational State Transfer ) .

• Representacional significa que transferimos a representação de um

recurso entre um servidor e um cliente. Usamos um formato de dados para
essa representação, normalmente JSON ou XML .

• Transferência de estado significa que cada operação com uma API REST
é autossuficiente . Cada requisição carrega (transfere) todas as
informações (estado) necessárias para concluir a operação.

As APIs REST normalmente usam métodos HTTP para recuperar ou enviar

informações entre aplicativos. Usamos os mesmos métodos HTTP quando
acessamos um site com um navegador, mas agora os utilizamos para interagir
com um aplicativo. O HTTP possui diversos métodos, mas estes quatro são os
mais comuns:
 • GET : Um método somente leitura para recuperar um recurso específico.

• POST : Envia dados para o recurso especificado para processamento. O

método POST também pode criar novos recursos.

• PUT : Atualiza o recurso especificado, substituindo os dados existentes.

• DELETE : Exclui o recurso especificado.

O HTTP é popular, então você pode usar APIs REST em praticamente qualquer
linguagem de programação.

Mencionei o recurso várias vezes, mas não expliquei exatamente o que é um

recurso. Um recurso é uma "coisa" à qual você pode ter acesso e da qual pode
receber ou alterar sua representação. Na web, isso pode ser um documento ou
uma imagem. Em uma API REST, pode ser uma linha em um banco de dados.

Acessamos um recurso com um Localizador Uniforme de Recursos (URL) . Isso

mesmo, as mesmas URLs que usamos para sites. Um exemplo rápido é a seguinte
URL:

[Link]

Podemos usar este URL para acessar o recurso Loopback 0 em um roteador.

Mostrarei em um minuto como isso funciona na prática.
Uma API deve atender a 6 restrições principais para ser considerada uma API
REST. Outro nome para uma API que atende a todas as restrições é serviço
RESTful . Compreender essas restrições em detalhes é essencial para
desenvolvedores de API.

As 6 restrições são:

• Cliente-servidor : O cliente e o servidor são independentes. Eles interagem

entre si por meio de requisições iniciadas pelo cliente. O servidor fica à
escuta das requisições e as responde.

• Sem estado : O servidor não armazena nenhum estado sobre solicitações

anteriores. Por exemplo, ele não registra se um cliente já solicitou um
recurso antes. Ele também não registra quais recursos foram solicitados
por um cliente.

• Armazenável em cache : O servidor inclui um número de versão em suas

mensagens. O cliente pode usar isso para decidir se deve solicitar um
recurso novamente ou usar os dados em cache.

• Interface uniforme : A interface é desacoplada da implementação.

Existem quatro sub-restrições:

o Identificação de recursos : Cada recurso deve ser identificável de

forma única por meio de um URI (Uniform Resource Identifier).

o Manipulação de recursos por meio de representações : Um

cliente não pode interagir diretamente com os recursos de um
servidor. Por exemplo, não é possível executar uma consulta SQL
diretamente do cliente no banco de dados do servidor. É necessário
usar uma representação e um formato de dados neutro. Quando um
cliente deseja atualizar um recurso, ele precisa seguir os seguintes
passos:

▪ Solicite uma representação do recurso.

▪ Atualize a representação com os novos dados.

▪ Enviar a representação do recurso para o servidor.

o Mensagens autodescritivas : Cada mensagem (solicitação ou

resposta) deve incluir informações suficientes para que o
destinatário a compreenda. Uma mensagem requer um tipo de
mídia (por exemplo, “application/json”) que indique ao destinatário
como interpretar a mensagem.
 o Hipermídia como mecanismo de estado da aplicação
(HATEOAS) : Você deve ser capaz de descobrir outras áreas da API
de forma semelhante à navegação de um usuário em um site. Uma
resposta da API deve incluir links para outras partes da API. Dessa
forma, você pode entender como a API funciona sem consultar
documentação externa.

• Sistema em camadas : REST permite um sistema em camadas. Você pode

implantar a API em um servidor e os dados em outro. É possível adicionar
camadas adicionais, como um balanceador de carga, entre o cliente e o
servidor. O cliente não consegue distinguir se está se comunicando com
um servidor intermediário ou com um servidor final. Camadas extras não
devem afetar a comunicação entre o cliente e o servidor.

• Código sob demanda (opcional) : Esta é uma restrição opcional. O

servidor geralmente envia uma representação estática em JSON ou XML. O
servidor pode, opcionalmente, incluir código executável para um cliente.
Um exemplo é um applet Java ou JavaScript.

A API REST não possui recursos de segurança integrados, mas podemos adicioná-
los se necessário. Por exemplo, podemos usar HTTPS para criptografia e nomes de
usuário ou tokens para autenticação. Você pode ler mais sobre isso na lição sobre
autenticação da API REST .

Configuração

Chega de teoria por agora. Vamos ver como podemos usar uma API REST para
monitorar e configurar um roteador Cisco CSR1000v. Aqui está a topologia que
usaremos:

O roteador possui uma interface loopback 0 que acessaremos e configuraremos

com alguns scripts Python no meu computador.

Roteador

Vamos começar pelo roteador. Este é um roteador CSR1000v com IOS XE 16.6.1:
R1#show version | include Version

Cisco IOS XE Software, Version 16.06.01

Cisco IOS Software [Everest], Virtual XE Software (X86_64_LINUX_IOSD-

UNIVERSALK9-M), Version 16.6.1, RELEASE SOFTWARE (fc2)

hostname R1

interface Loopback0

ip address [Link] [Link]

interface GigabitEthernet2

ip address [Link] [Link]

negotiation auto

no mop enabled

no mop sysid

ip route [Link] [Link] [Link]

end

Primeiro, criamos um usuário que tenha acesso total ao roteador:

R1(config)#username admin privilege 15 password admin

Além disso, ativamos a interface de gerenciamento compartilhada:

R1(config)#virtual-service csr_mgmt

R1(config-virt-serv)#ip shared host-interface GigabitEthernet 2

R1(config-virt-serv)#activate

% Activating virtual-service 'csr_mgmt', this might take a few minutes. Use 'show
virtual-service list' for progress.

Essa configuração é tudo o que precisamos fazer para habilitar a API REST.
Existem alguns comandos que podemos usar para verificar se a API REST está
ativa. Os dois primeiros comandos servem para verificar o status do serviço
virtual:

R1#show virtual-service list

Virtual Service List:

Name Status Package Name

------------------------------------------------------------------------------

csr_mgmt Activated [Link]

Se você quiser mais detalhes, tente isto:

R1#show virtual-service detail name csr_mgmt

Virtual service csr_mgmt detail

State : Activated

Owner : IOSd

Package information

Name : [Link]

Path : bootflash:/[Link]

Application

Name : csr_mgmt

Installed version : 2017.6

Description : CSR-MGMT

Signing

Key type : Cisco release key

Method : SHA-1

Licensing

Name : Not Available

Version : Not Available

 Detailed guest status

----------------------------------------------------------------------

Process Status Uptime # of restarts

----------------------------------------------------------------------

nginx UP 0Y 0W 0D 0: 4:36 0

climgr UP 0Y 0W 0D 0: 4:36 1

restful_api UP 0Y 0W 0D 0: 4:36 0

fcgicpa Down

pnscag Down

pnscdme Down

----------------------------------------------------------------------

Feature Status Configuration

----------------------------------------------------------------------

Restful API Disabled, UP

PNSC Disabled, Down

Network stats:

eth0: RX packets:807, TX packets:795

eth1: RX packets:29, TX packets:28

Coredump file(s): R1_climgr_67_20190925-[Link], lost+found

Activated profile name: None

Resource reservation

Disk : 756 MB

Memory : 512 MB

CPU : 5% system CPU

Attached devices

Type Name Alias

---------------------------------------------

NIC ieobc_1 ieobc

NIC dp_1_33 net2

Disk _rootfs

Disk /opt/var

Disk /opt/var/c

Serial/shell serial0

Serial/aux serial1

Serial/Syslog serial2

Serial/Trace serial3

Watchdog watchdog-2

Network interfaces

MAC address Attached to interface

------------------------------------------------------

54:0E:00:0B:0C:02 ieobc_1

FA:16:3E:DA:62:4F VirtualPortGroup33

Guest interface

---

Interface: eth1

ip address: [Link]/24

---
 Guest routes

---

Address/Mask Next Hop Intf.

-------------------------------------------------------------------------------

---

Resource admission (without profile) : passed

Disk space : 756MB

Memory : 512MB

CPU : 5% system CPU

VCPUs : Not specified

Outro comando é show remote-managementeste, que fornece uma visão geral

rápida:

R1#show remote-management status

Remote management release version: 2017.6

----------------------------------------------------------------------

Process Status Uptime # of restarts

----------------------------------------------------------------------

nginx UP 0Y 0W 0D 0: 3: 3 0

climgr UP 0Y 0W 0D 0: 3: 3 1

restful_api UP 0Y 0W 0D 0: 3: 3 0

fcgicpa Down

pnscag Down

pnscdme Down

----------------------------------------------------------------------

Feature Status Configuration

----------------------------------------------------------------------

Restful API Disabled, UP

PNSC Disabled, Down

Network stats:

eth0: RX packets:554, TX packets:548

eth1: RX packets:29, TX packets:28

Isso é tudo o que precisamos configurar no nosso roteador.

Python

Eu escrevi dois scripts em Python 3 para interagir com o nosso roteador. Você
pode encontrá-los no meu repositório Gitlab CSR1000V REST API .

Interface GET

Vamos começar com um exemplo simples. O script possui duas funções:

o obter_token

o obter_interface

Primeiro, autenticamos com o roteador usando um nome de usuário e senha. Se a

autenticação for bem-sucedida, recebemos um token. Em seguida, usamos o
método HTTP GET para recuperar informações sobre a interface de loopback 0.
Vamos executar o script:

python [Link]

We received token: VqtX5iHJpURytNQYoTF2S1zFdJIRgmAPF8ZM4v9h+gE=

Here is the interface information:

"kind": "object#interface",

"description": "",
 "if-name": "Loopback0",

"proxy-arp": true,

"subnet-mask": "[Link]",

"icmp-unreachable": true,

"ipv6-enable": false,

"nat-direction": "",

"icmp-redirects": true,

"ip-address": "[Link]",

"verify-unicast-source": false,

"type": "loopback"

A saída acima parece correta. O roteador reporta a configuração da interface

loopback 0.

Interface PUT

O segundo script utiliza o método HTTP PUT para reconfigurar nossa interface de
loopback 0. Ele possui duas funções:

• obter_token

• colocar_interface

A função `get_token` é a mesma do nosso script anterior. A função

`put_interface` adiciona um cabeçalho que especifica que a carga útil está em
formato JSON. Em seguida, enviamos a carga útil com nossa configuração
atualizada para o roteador.

python [Link]

We received token: VqtX5iHJpURytNQYoTF2S1zFdJIRgmAPF8ZM4v9h+gE=

The router responds with status code: 204

O roteador responde com um código de status 204. Esse código de status significa
que o servidor atendeu à solicitação com sucesso e que não há conteúdo
adicional a ser enviado.

Conclusão

Agora você aprendeu o que é uma API REST e como usá-la no roteador Cisco
CSR1000v.
 • Uma API é uma interface de software que permite que outros aplicativos
interajam com a nossa aplicação.

• REST é um estilo de arquitetura descrito em uma dissertação de Roy T.

Fielding.

• Uma API REST é uma API que atende a 6 restrições.

• A maioria das APIs REST utiliza métodos HTTP e JSON ou XML como
formato de dados.

• Utilizamos o método HTTP GET para obter informações da interface e o

método HTTP PUT para atualizar sua configuração.

Espero que tenha gostado desta aula. Sinta-se à vontade para deixar um
comentário caso tenha alguma dúvida.