Descubra a magia das API’s com Harry Potter — Pt 2
Prosseguindo com nossos estudos sobre API’s, neste estágio você já deve ter sua chave de acesso!
Se você não sabe do que se trata ou é o primeiro post sobre o assunto que está lendo, considere visitar a parte 1 deste tutorial neste link!
Fazendo requisições com uma chave de API
Agora podemos utilizar a chave que obtemos para fazer requisições a um endpoint diferente, desta vez será o spells .
O primeiro passo é similar ao que fizemos anteriormente, construiremos a URL composta pela URL base e o endpoint.
# Construindo a nova URL
# url base continua sendo a mesma
endpoint_url = "spells"
url = base_url + endpoint_url
# Visualizando a url
print(url)Se nesse momento você tenta acessar a url utilizando os mesmo comandos mostrados anteriormente ou até mesmo como um endereço web, obterá a seguinte mensagem:
"error": "Must pass API key for request"
Nós precisaremos então adicionar a chave da API na requisição para que ocorra a autenticação. Porém não é simplesmente adicionar a chave ao final da URL como fizemos com o endpoint, deste modo a API pensará que a chave faz parte da URL e acabaremos por requisitar dados de um enpoint que não existe. Logo, precisamos adicionar a chave como um parâmetro.
Parâmetros da URL
Parâmetros são pedaços extras de informação que a API está apta a receber. Cada parâmetro tem um nome e um valor e são adicionados à URL com uma sintaxe especial, fazendo com que a API consiga interpretá-los desse modo.
Adiante neste tutorial nós usaremos diversos parâmetros, porém para esta chamada nós usaremos apenas um, o parâmetro de chave.
# Adicionando o parâmetro na URLurl = url_base + endpoint_url + "?key=" + chave_api# Visualizando a URL
print(url)
https://www.potterapi.com/v1/spells?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
O caractere “?” faz com que a API pare de ler a URL como um endereço a partir desse ponto e comece a tratar os dados inseridos como parâmetros. Em seguida vem o nome do parâmetro — key — seguido por um sinal de igual e o atual valor. Nesse caso eu substitui o valor real por um fictício por questões de segurança.
Ao receber essa requisição, a API começará a identificar a parte da URL que corresponde a um endereço e direcionará através do enpoint, e então irá extrair quaisquer parâmetros inseridos, fazendo a verificação de nome e valor para finalmente liberar o acesso à determinado endpoint ou não.
Extraindo os dados
O endpoin spells é um pouco mais complicado que o sortinhat e retorna um número maior de dados. Para extrair informações significativas, teremos que passar por um número maior de passos.
O começo como sempre é o mesmo, acessaremos os dados utilizando o método .json() .
# Acessando os dadosdados = resposta.json()# Verificando o tipo de dado retornadoprint(type(dados))
<class ‘list’>
O objeto retornado desta vez é uma lista, nós precisaremos efetuar loops para acessar os detalhes de cada feitiço.
Começaremos olhando o primeiro item da lista.
# Verificando o tipo de dado do primeiro item da lista
print(type(dados[0]))<class ‘dict’>
# Exibindo o primeiro item da lista
print(dados[0]){‘_id’: ‘5b74ebd5fb6fc0739646754c’, ‘spell’: ‘Aberto’, ‘type’: ‘Charm’, ‘effect’: ‘opens objects’}
Podemos então verificar que a lista é composta de elementos do tipo dicionário composto de pares de chave:valor . Agora que entedemos a estrutura dos dados nesse endpoint, podemos acessá-los de modo mais apropriado.
Como o método .json() converte tudo em objetos que o Python trabalha, qualquer coisa que normalmente faríamos em Python é valida aqui. Com apenas mais uma linha de código, podemos descobrir o número total de feitiços.
# Exibindo o número de feitiços.
print(len(dados))151
Também é possível extrair o nome dos feitiços presentes nesta lista
# Loop através dos 5 primeiros items na lista, exibindo o nome de cada um deles.for item in dados[:5]:
print(item["spell"])
Aberto
Accio
Age Line
Aguamenti
Alarte Ascendare
E com um exemplo um pouco mais complexo, podemos efetuar a contagem de feitiços por tipo, veja a seguir:
# Contagem dos feitiços de cada tipo existentecontagem_de_feitiços = {}
for item in dados:
if item["type"] not in contagem_de_feitiços:
contagem_de_feitiços[item["type"]] = 1
else:
contagem_de_feitiços[item["type"]] += 1for chave in contagem_de_feitiços:
print(chave + ":", contagem_de_feitiços[chave])
Charm: 40
Enchantment: 1
Spell: 92
Hex: 1
Curse: 15
Jinx: 2
Parâmetros
O parâmetro chave é necessário para acessar todos os endpoints exceto o sortinghat , porém não é o único existente. Consultando a documentação da API, você pode aprender quais endpoints a API aceita e quais os parâmetros correspondentes.
Parâmetros podem ser utilizados para filtrar os dados, retornando apenas subconjuntos dos dados disponíveis. Para explorar um pouco mais essa funcionalidade, usaremos o endpoint characters , que possui dados dos personagens e aceita diversos parâmetros.
Acessando personagens
# Construindo a URL
endpoint_url = "characters"
url = url_base + endpoint_url + "?key=" + chave_api
# Solicitando os dados dos personagens
response = requests.get(url)
# Verificando o código de resposta
print(response.status_code) 200
# Extraindo os dadosdados = response.json()# Efetuando a contagem do número de personagensprint(len(dados))
195
Adicionando mais parâmetros
Para adicionar mais parâmetros, filtrando ainda mais os dados, pordemos adicioná-los ao final da URL. O caractere “&” é utilizando para conectar diferentes parâmetros.
# Adicionando mais uma parâmetro à URLurl = url + "&ministryOfMagic=True"# Solicitando os dados de todos os personagens que fazem parte do Ministério da Magiaresposta = requests.get(url)# Extraindo os dados dados = resposta.json()# Efetuando a contagem print(len(dados))
22
Com isso obtemos que 22 dos personagens de Harry Potter são do ministério da magia, você pode verificar o nome de cada um assim como fizemos com os feitiços se desejar.
Podemos ainda adicionar mais parâmetros, filtrando ainda mais os dados, o exemplo abaixo, faz uma requisição para retornar todos os nascidos trouxas da casa de Grifinória.
# Construindo a URL
url = url_base + endpoint_url + \ "?key=" + chave_api + \ "&bloodStatus=muggle-born&house=Gryffindor"# Solicitando os dadosresposta = requests.get(url)# Extraindo os dadosdados = resposta.json()# Exibindo os nomesfor item in dados:
print(item["name"]
Colin Creevey
Dennis Creevey
Hermione Granger
Lily J. Potter
Conclusões finais
Existe um mundo de API’s e processos mais complexos que podemos efetuar com elas que merece ser explorado, espero que esse post tenha desvelado alguns conceitos e exemplificado os passos necessários para acessar uma API.
Não há jeito melhor de melhorar suas habilidades com API’s do que encontrar alguma relacionada a um assunto que você realmente goste e começar a explorar. Diferentes API’s possuirão diferentes regras e documentações, mas os princípios de acesso serão muito similares aos encontrados aqui: Encontrar um endpoint para efetuar a requisição e incluir parâmetros para filtrar os dados. Sem contar que as documentações são em sua maioria bem claras e acessíveis.
Como dica final, deixo este repositório do GitHub que contém uma imensa quantidade de API’s públicas e acessíveis para você explorar.
Obrigado por sua leitura até aqui!
