Descubra a magia das API’s com Harry Potter — Pt 1
Atualmente, as API’s são peças fundamentais de diversos serviços e softwares que utilizamos diariamente e, nas mãos de um desenvolvedor, podem se tornar poderosas ferramentas. Aprender como manipulá-las nos abre um infinito mundo de novas possibilidades com a programação.
Neste post aprenderemos de forme breve como nos conectar com uma API utilizando Python.
O que é uma API?
Uma API (Application Programming Interface) ou Interface de Programação de Aplicativos pode ser compreendida inicialmente como um serviço que nos provê dados quando o requisitamos. Constituindo um conjunto de rotinas e padrões de programação para acesso a um aplicativo ou plataforma baseada na web, de modo a permitir que diferentes máquinas e programas comuniquem-se entre si através da programação.
Elas estão por toda parte, temos API’s meteorológicas, que nos fornecem diversos dados sobre o clima, outras que nos permitem visualizar dados de diversos filmes lançados e até mesmo uma para nos dar acesso a imagem de gatinhos.
Você que acessa a internet diariamente interage, mesmo sem saber, com API’s o tempo todo, como quando acessa um mapa interativo num aplicativo de transportes, ou vê uma lista de produtos recomendados em um site.
Acessando uma API
Existem dois pontos centrais que você precisa saber antes de acessar uma API.
- Onde encontrar a API (endpoint).
- Como fazer a requisição de dados.
Os endpoints de uma API
Se você quer obter respostas, precisa saber como e onde perguntar.
O endereço que as API’s fornecem para os usuários efetuarem as requisições de dados é chamado de endpoint. Algumas possuem apenas um, respondendo a apenas um tipo de requisição. A maioria porém, possuem diversos endpoints, cada um responsável por diferentes tipos de informação.
A API de Harry Potter que será o nosso exemplo, possui o seguinte endereço base: https://www.potterapi.com/v1/ e então, diversos endpoints. O mais simples deles, se você quiser, por exemplo, obter uma casa de Hogwarts aleatoriamente, é o endpoint do sortinghat. O endereço inteiro para esse endpoint fica de seguinte forma: https://www.potterapi.com/v1/sortinghat .
Uma vez que as API’s realizam a comunicação utilizando o protocolo HTTPS, o endpoint é um endereço web válido, que você pode acessar. Neste caso, visitar o endereço fará com que você obtenha uma casa de Hogwarts de modo aleatório.
Acesse o endpoint do sorting hat de Harry Potter.
As chamadas de uma API
De forma simples, a requisição de uma API é apenas o endereço do endpoint da mesma. Fazer uma chamada é quando você acessa um endpoint com uma requisição.
O link acima te possibilita a acessar o endpoint sortinghat manualmente. Do ponto de visto humano, você clica no link e visita um outro site. O que acontece de fato é que, ao clicar no link, o seu navegador faz uma requisição ao endpoint da API, que mandará de volta um dado em formato JSON, que então será exibido para você. Não precisamos pensar nas requisições que vão e vêm pela rede, mas é importante estar ciente das mesmas quando falamos de API’s.
Nem todas as requisições são simples assim. Alguns endpoints esperam por informações extras nas requisições e retornam dados diferentes de acordo com os parâmetros que você fornece. Alguns necessitam de autenticação e só retornarão dados para requisições que contenham uma chave secreta, falaremos disso adiante.
Documentações de API’s
Apesar de muitas API’s trabalharem de modo similar, sempre teremos que pesquisar um pouco para saber quais são os exatos endpoints de uma API ou como nossas requisições serão realizadas. Pra nossa sorte, a maioria delas vem com documentações detalhadas, incluindo exemplos de requisições e os dados que elas retornam.
A documentação da API de Harry Potter explica a finalidade de cada endpoint e como usá-lo.
Acessando uma API utilizando Python
Embora possamos acessar uma API do mesmo jeito que um usuário acessa um site, a finalidade delas não é bem essa. Uma vez que são feitas para serem acessadas através de código, aprenderemos agora como acessar o endpoint sortinghat utilizando Python!
Importando bibliotecas
Para acessar a API de Harry Potter, precisamos apenas de uma biblioteca, a requests que nos permitirá realizar requisições HTTPS com o Python. Basta importar essa biblioteca.
import requests #Permite realizar chamadas aos endpoints da API.Construindo a URL
O próximo passo é construir a URL, o endereço que iremos requisitar os dados.
Poderíamos simplesmente guardar a URL em uma variável para requisição porém, uma boa prática seria inicialmente “dividir” a URL em pequenos pedaços e então conectá-los, tornando mais fácil a edição da URL e a criação de novas futuramente. Veja o exemplo:
# Criando os componentes da URLurl_base = "https://www.potterapi.com/v1/"
endpoint_url = "sortinghat"
# Juntando os pedaços
url = url_base + endpoint_url
# Visualizando a URLprint(url)
Realizando a requisição
Com a URL construída, podemos utilizar o método .get() da biblioteca requests para requisitar respostas da API. Existem outros tipos de requisições que poderíamos utilizar, porém na maioria dos casos lidando com API’s, trabalharemos com as requisições do tipo GET: a requisição HTTPS que solicita respostas.
# Realizando uma requisiçãoresposta = request.get(url)
Como resposta à nossa requisição, obtemos um objeto resposta que não apenas contém os dados, mas informações importantes da requisição e como ela foi recebida.
Todos os objetos do tipo resposta possuem um código de status HTTP, que são basicamente 3 dígitos que nos dizem se a requisição foi realizada com sucesso e, caso contrário, o que deu errado. Provavelmente você está familiarizado com alguns códigos de status como o 404, código de status para quando a fonte requisitada não pôde ser encontrada. Existem muitos códigos diferentes, cada um com seu significado.
O código para uma requisição realizada com sucesso é o 200.
# Verificar o código de status do objeto respostaprint(resposta.status_code)
200
Obtendo os dados
Finalmente, precisamos extrair os dados do objeto resposta . Como mencionado anteriormente, a API nos retorna dados no formato JSON, que significa JavaScript Object Notation, e é um dos formatos de dados mais populares, sendo relativamente leve, fácil de ler e de operar com a maioria das linguagens.
O objeto resposta possui um método nativo chamado .json() que extrai os dados do formato JSON e retorna como a estrutura de dados em Python mais apropriada. Neste caso inicial, é uma simples string.
# Acessando os dadosdados = resposta.json()# Visualizando os dadosprint(dados)
Gryffindor
Obs: A cada vez que rodar o código, uma nova casa será exibida aleatoriamente.
Obtendo a chave de uma API
A API de Harry Potter não requer uma autorização para acessar o endpoint sortinghat , porém para qualquer outro endpoint se faz necessário uma chave de segurança, que você pode obter de graça criando uma conta com um e-mail válido.
Uma vez criada, você receberá sua chave única para utilizar na API.
Chaves de API devem ser mantidas em segurança — não as compartilhe com ninguém!
No exemplo abaixo eu substitui minha chave de API por outros caracteres.
# Guardando a sua chave de API como uma variávelchave_api = 'XXXXXXXXXXXXXXXXXX'
Agora que você já possui sua própria chave, podemos acessar outros endpoints da API e isso você encontra na segunda parte deste tutorial!
