Java: consumindo API, gravando arquivos e lidando com erros

Requisições e respostas - Apresentação

Jacqueline: Olá, tudo bem? Eu sou a Jacqueline Oliveira, instrutora na Alura, e te dou boas-vindas a mais um curso da nossa formação Java. Dessa vez, vamos aprender sobre APIs, bibliotecas externas e arquivos.

Sou uma mulher branca com cabelos loiros longos, com uma camiseta azul marinho com o logo da Alura.

Estou aqui com o Paulo.

Paulo: Oi, Jaque. Eu sou o Paulo Silveira e estou muito contente em poder dar esse avanço na formação de Java.

Sou um homem branco, na faixa dos 40 anos, com cabelos curtos, barba e bigode, todos pretos, além de uma camiseta cinza do super nintendo e calça preta.

Nesse curso, vamos aprender diversas coisas que podem ser aplicadas no mundo real, como consumir um serviço de web services, usar uma API, testar, trabalhar com as exceptions e posteriormente reorganizar o código. Isso porque ao longo da formação, construímos um código grande. Então, como colocamos isso em classes, ou até mesmo em interfaces.

Como pesquisar por algo no Google para saber se já não existe uma solução que resolva determinado problema em Java? É bem interessante visualizar a orientação a objetos e encapsulamento sendo aplicado.

Vamos solucionar um problema real: de consumir um serviço, compreender o que está acontecendo por trás e utilizar as ferramentas adequadas para solucionar as questões do cotidiano em empresas.

Vamos lá?

Requisições e respostas - Conhecendo uma API para buscar dados

Paulo: Jaque, temos em um site que contém uma API, o OMDb API . Essa palavra "API" ganhou diversos significados, o Java.util, por exemplo, é uma API onde fazemos chamadas para a biblioteca padrão do Java que possui as coleções que usamos bastante.

Atualmente, isso tem crescido e a API significa também programas que podemos acessar na web de forma remota de outro site, realizar uma chamada para uma API (isto é, enviar e receber informações) geralmente via HTTP. São as chamadas de serviços e consumir os microsserviços, algo bem comum e que fazemos o dia todo.

O interessante é que com o conhecimento que já temos sobre o Java, conseguimos consumir uma API e resolver um problema. No caso, escolhemos o OMDb API, porém, há diversos outros sites, como o AdoroCinema, o Rotten Tomatoes, o IMDb e o Omelete, entre outros sites que oferecem dados sobre filmes e séries.

O OMDb oferece uma API. Informando que se passarmos uma mensagem em um determinado padrão, é devolvida uma resposta em determinado padrão também. E, com isso, conseguimos buscar os Webviews, o avatar e pegar essas informações.

Assim, não temos mais um sistema fictício onde está tudo escrito no public static void main. Estamos conectando na Internet, puxando e minerando esses dados, e exibindo somente o que desejamos. Isso é o que acontece em uma aplicação real, seja no back-end (como estamos fazendo aqui), ou no dispositivo móvel, ou para o front-end onde passamos essa informação para o React.

Nesse curso, vamos aplicar coisas do mundo real. Gostaria de entender como funciona essa API e como exploramos? Temos no menu superior do OMDb uma API Key, parâmetros, exemplos, entre outras abas.

As diversas APIs possuem documentações diferentes. E isso é um desafio que seria interessante você passar com a Jacqueline e comigo: conhecer a documentação de uma biblioteca na web ou uma API na web, saber chamá-la, e realizar testes, são coisas aplicadas no cotidiano.

Você vai ver que a Jacqueline e eu vamos passar por alguns problemas ao longo do curso. Por exemplo, levantando questões do tipo: será que precisamos de uma biblioteca Java para isso? Será que precisamos criar um login e uma senha? Precisamos criptografar os dados? Como podemos testar sem ser de forma manual?

São desafios bem comuns no cotidiano de pessoas desenvolvedoras não apenas de Java.

Jacqueline: Exatamente. No cotidiano trabalhamos integrando sistemas e muitas vezes precisamos consumir esses serviços. Nessa API, por exemplo, podemos fazer a requisição e receber uma resposta.

Descendo a página inicial do OMDb API, em "Usage" (em português, "uso"), temos como deve ser usado. Precisamos realizar uma requisição para um determinado endereço e ter uma chave. Já vamos entender melhor sobre isso.

"Usage" retirado do site do OMDb API

• Send all data requests to: http://www.omdbapi.com/?apikey=[yourkey]&
• Poster API requests: http://img.omdbapi.com/?apikey=[yourkey]&

Descendo um pouco mais, temos alguns parâmetros (seção "Parameters") que podemos passar na URL para identificar se vamos buscar um título pelo ID ou pelo nome (By ID or Title). Já temos uma documentação bem básica sobre essa API para entendermos como ela funciona.

Paulo: Uma documentação meio primitiva.

Jacqueline: Sim.

Paulo: É comum testarmos para verificar se é da forma que entendemos mesmo.

Jacqueline: Nessa documentação temos até uma seção "Examples" (em português, "exemplos"). Nessa parte, temos uma busca por título (by title) e outra por ID (by ID). Se buscarmos pelo título "Matrix" no campo Title e teclarmos "Enter", obtemos o seguinte JSON com o exemplo do retorno:

{"Title":"Matrix","Year":"1993","Rated":"N/A","Released":"01 Mar 1993","Runtime":"60 min","Genre":"Action, Drama, Fantasy","Director":"N/A","Writer":"Grenville Case","Actors":"Nick Mancuso, Phillip Jarrett, Carrie-Anne Moss","Plot":"Steven Matrix is one of the underworld's foremost hitmen until his luck runs out, and someone puts a contract out on him. Shot in the forehead by a .22 pistol, Matrix \"dies\" and finds himself in \"The City In Between\", where he is ...","Language":"English","Country":"Canada","Awards":"1 win","Poster":"https://m.media-amazon.com/images/M/MV5BYzUzOTA5ZTMtMTdlZS00MmQ5LWFmNjEtMjE5MTczN2RjNjE3XkEyXkFqcGdeQXVyNTc2ODIyMzY@._V1_SX300.jpg","Ratings":[{"Source":"Internet Movie Database","Value":"7.8/10"}],"Metascore":"N/A","imdbRating":"7.8","imdbVotes":"199","imdbID":"tt0106062","Type":"series","totalSeasons":"N/A","Response":"True"}

Em "Request" temos:

http://www.omdbapi.com/?t=matrix

Se digitarmos essa URL incluindo a chave no final, temos a resposta em JSON que ele nos informou.

Paulo: Essa estrutura da resposta entre chaves com vários elementos dentro pode assustar de primeira, mas isso é um formato JSON.

JSON: JavaScript Object Notation

O formato do JSON até lembra um pouco o XML ou txt puro, que é possível encadear informações. Por exemplo, a parte que tem o "Title":"Matrix", ai seguido da vírgula o "Year":"1993",, perceba que são apenas dados encadeados em um formato específico.

Essa é o formato mais usado, tanto que vamos pesquisar sobre bibliotecas Java que possam pegar esse tipo de texto (dado que isso seria uma string grande) e convertê-lo em um objeto.

Também já nos fornecei um exemplo omdbapi.com/?t=matrix, assim ele já nos retorna o filme chamado de Matrix.

Jacqueline: Na API Key precisamos passar uma API Key. Se tentarmos acessar o endereço que ele gerou para nós pelo navegador (http://www.omdbapi.com/?t=matrix), obtemos:

{"Response":"False","Error":"No API key provided."}

Observe que ele foi informado que não passamos nenhuma API Key, logo, ele não exibe as informações para nós.

Paulo: Essa chave da API é para sabermos com quem estamos falando, não é?

API Key: chave de acesso da API

Jacqueline: Exato! Quem está nos pedindo essa informação e para quem estamos devolvendo? É como se fosse uma identificação.

Paulo: Funciona como se estivesse controlando, se não muitas pessoas poderiam tentar acessar e derrubar o site de tanto acesso. Existem APIs que são mais delicadas, como essa que estamos usando que provavelmente é uma API apenas de leitura, para consumirmos informações.

Existem também APIs de escrita. Assim é necessário saber quem está escrevendo e se comunicando com a API. Então há chaves ou outros mecanismos para conseguirmos identificar quem está chamando do outro lado da web. E estamos usando web pura, não é, Jaque?

Jacqueline: Isso.

Paulo: Esse é um site, e o site nos devolveu dados entre chaves. Tudo isso está acontecendo via protocolos mais básicos da web, como o HTTPS e com IP. É o protocolo da web, que está envolvido com serviços, como o web services e microservices.

Jacqueline: Exatamente, Paulo.

No site do OMDb API, clicamos em "API Key" no menu superior do lado direito e fazer o nosso cadastro. Temos as opções "Patreon" e "FREE! (1,000 daily limit)", a primeira é para ser um patrocinador ou fazer doações, e a segunda é para termos acesso gratuito com mil requisição por dia. Podemos usar essa última opção que é mais que o necessário para o nosso cenário.

No formulário exibido, marque a opção FREE! (1,000 daily limit) no campo Account Type e preencha os campos Email e Name com o seu email e nome. No campo Use, coloque o seguinte texto: Personal application for test purpose e clique no botão "Submit"

Você receberá um email com a sua chave e também um link para fazer a ativação dela. Clique neste link para realizar a ativação e sua chave estará pronta para ser utilizada.

Já tenho a minha chave, mas é necessário que você gere a sua. A minha chave, por exemplo, temos o título Top Gun e observe que no endereço após o key = temos o número 6585022c, sendo onde está a chave. As nossas requisições a partir de agora serão feitas dessa maneira.

Endereço indicado pela instrutora: https://www.omdbapi.com/?t=top+gun&apikey=6585022c

Paulo: Sempre com a API Key, né?

Jacqueline: Isso mesmo.

Paulo: Chamamos essa parte da URL de query string. Há diversas formas de enviarmos queries em sites, mas neste caso é dessa forma.

Jacqueline: Exato.

https://www.omdbapi.com/?t=top+gun&apikey=6585022c

Observe que em top+gun foi passado o nome do título que desejamos consultar e depois a api key. Em suma, é disso que precisamos.

Estamos desenvolvendo um aplicativo chamado de ScreenMatch, e desejamos, por exemplo, fazer uma parte do aplicativo onde seja possível a pessoa usuária informar o que deseja assistir no site. Assim, a pessoa usuária informa o filme que ela gostaria que tivesse na plataforma.

Imagine o tamanho do catálogo que não teríamos, se temos mecanismos para a pessoa usuária buscar, é o que vamos aplicar no nosso caso. Implementaremos essa busca. Pesquisamos no Java o filme que desejamos e ele virá na API realizar essa busca para nós.

Paulo: Então o nosso desafio será como acessamos, em Java, o https://www.omdbapi.com/?t. Até mesmo porque não aprendemos isso. Qual a biblioteca que pode se conectar no nosso endereço, como vamos capturar o conteúdo da página (JSON) e posteriormente provavelmente vamos precisar de uma biblioteca para fazer essa HTTP connection (conexão HTTP).

Após pegarmos esse conteúdo, como convertemos na nossa classe (que usamos ao longo dessa formação) para popularizar esse objeto a partir do JSON. Acredito que vamos ver duas bibliotecas para isso, se instalamos no IntelliJ ou se será somente importação e essas coisas vão começando a se encaixar.

Lembrando que vamos deixar o link para a API e para o GitHub, e todos os outros links que precisamos para trabalhar com essa API.

Jacqueline: Exatamente. Vamos lá?

Requisições e respostas - Fazendo requisições com o Postman

A instrutora está com a seguinte estrutura JSON na tela:

{"Title":"Top Gun","Year":"1986","Rated":"PG","Released":"16 May 1986","Runtime":"109 min","Genre":"Action, Drama","Director":"Tony Scott","Writer":"Jim Cash, Jack Epps Jr., Ehud Yonay","Actors":"Tom Cruise, Tim Robbins, Kelly McGillis","Plot":"As students at the United States Navy's elite fighter weapons school compete to be best in the class, one daring young pilot learns a few things from a civilian instructor that are not taught in the classroom.","Language":"English","Country":"United States","Awards":"Won 1 Oscar. 11 wins & 6 nominations total","Poster":"https://m.media-amazon.com/images/M/MV5BZjQxYTA3ODItNzgxMy00N2Y2LWJlZGMtMTRlM2JkZjI1ZDhhXkEyXkFqcGdeQXVyNDk3NzU2MTQ@._V1_SX300.jpg","Ratings":[{"Source":"Internet Movie Database","Value":"6.9/10"},{"Source":"Rotten Tomatoes","Value":"58%"},{"Source":"Metacritic","Value":"50/100"}],"Metascore":"50","imdbRating":"6.9","imdbVotes":"469,093","imdbID":"tt0092099","Type":"movie","DVD":"20 Oct 1998","BoxOffice":"$180,258,178","Production":"N/A","Website":"N/A","Response":"True"}

Paulo: Jaque, podemos usar via web, mas há situações em que a query da URL começa a ficar grande. Há momentos que precisamos enviar coisas através do post, onde precisamos abrir o inspect do navegador e escrever algumas instruções em JavaScript ou outra linguagem. Deve ter ferramentas mais interessantes para fazermos isso, não?

Jacqueline: Exato.

Como vimos na API, podemos passar vários parâmetros na documentação. Teríamos que ficar concatenando pelo nevagdor e isso ficaria ruim, podemos passar o tipo e etc. Logo, vamos usar alguma ferramenta para fazermos isso.

Nesse curso, vamos usar o Postman sendo uma ferramenta bastante usada pelas pessoas desenvolvedoras. Mas há outras, como o Insomnia.

https://www.omdbapi.com/?t=top+gun&apikey=6585022c

Copiamos a URL acima e vamos fazer essa mesma requisição pelo Postman. No Postman, no canto superior esquerdo podemos selecionar o ícone de mais "+" que será aberta uma aba com um campo para inserirmos o endereço e um método para selecionarmos.

Para fazermos uma requisição HTTP do tipo get (verbo), colamos o nosso endereço no campo ao lado do verbo. Observe que ele já identificou dois parâmetros em "Params", sendo o que colocamos como busca e a nossa API Key:

Na URL, ao invés de top+gun colocamos matrix.

https://www.omdbapi.com/?t=matrix&apikey=6585022c

Paulo: Ou editando no value mesmo, né?

Jacqueline: Sim, podemos editar pelo value direto. Clicando no botão "Send", obtemos um JSON:

{
        "Title": "Matrix",
        "Year": "1993",
        "Rated", "N/A",
        "Released": "01 Mar 1993",
        "Runtime": "60 min",
        "Genre": "Action, Drama, Fantasy",
        …
}

Note que ele até chama essa formatação mais legível de Pretty (canto superior do retorno do body). Isso porque está um elemento abaixo do outro, com seus atributos e valores, respectivamente.

Paulo: O Postman é um sistema na web ou que podemos instalá-lo na nossa máquina, onde conseguimos guardar o endereço para usá-lo e alterá-lo posteriormente. Muita gente usa essa ferramenta para debugar (identificar e corrigir erros ou bugs).

Jacqueline: Exato, e conseguimos fazer isso usando o Postman. Podemos editar pelo value, por exemplo, ao invés de matrix colocamos divertidamente.

Ao selecionarmos "Send", temos:

O retorno abaixo foi parcialmente transcrito. Para conferi-lo na íntegra, execute o código na sua máquina.

{
        "Title": "Divertidamente",
        "Year": "2018",
        "Rated", "N/A",
        "Released": "11 Mar 2018",
        "Runtime": "N/A",
        "Genre": "Action, Drama, Fantasy",
        "Director": "N/A",
        "Writer": "N/A",
        "Actors": "N/A",
        "Plot": "N/A",
        "Language": "Portuguese",
        "Country": "Portugal",
        "Awards": "N/A",
        "Poster": "N/A",
        "Ratings": [],
        "Metascore": "N/A",
        …
}

Não devolveu tanta informação por ser uma animação, mas ele localizou pela busca qual o filme.

Ao iniciarmos o Postman, ele estará na tela "Create an account or sign in" (em português, "Crie uma conta ou faça login"). Caso queira usar somente para testes, basta selecionar a opção "Skip and go to the app" (em português, "Pular e ir para o aplicativo") na parte inferior esquerda.

Create your account or sign in later? Skip and go to the app

Mas caso queira, pode criar a sua conta para sincronizar com os seus projetos. Fica a seu critério isso.

Paulo: Relembrando que a API Key é a sua própria e não a que estamos usando aqui. Você precisa substituir para não dar erro informando que não há autorização ou que a API Key não é válida.

Vamos alterar, inclusive, o número no final do endereço.

Jacqueline: Vou alterar aqui para "1111" e clicar no botão "Send".

https://www.omdbapi.com/?t=matrix&apikey=1111

Como retorno, obtemos:

{
        "Response": "False",
        "Error": "Invalid API Key!"
}

Paulo: Informa que a API Key informada não é válida, logo, você deve inserir a sua chave. Também é possível explorar bastante, como buscar pelo ano de lançamento e visualizar uma lista de filmes, quando um nome é semelhante ao outro, etc. Talvez na documentação não esteja tão claro assim, então testamos a API pelo Postman.

Isso é muito comum no cotidiano de pessoas desenvolvedoras não somente em Java. Normalmente nas empresas chamamos APIs de outras empresas ou até mesmo temos o sistema quebrado em microsserviços. O que está acontecendo por trás dessa API está encapsulado, não é, Jaque?

Jacqueline: Exatamente.

Paulo: Está escondido, não sei dizer se há um banco de dados do MySQL Oracle, ou se está em um arquivo texto ou se o OMDb pesquisa em alguma API. Repare que esse mecanismo de encapsulamento e até acoplamento, nós tentamos diminuir para encapsular.

Esses princípios da orientação a objetos ocorre em nível macro da web, como podemos observar.

Jacqueline: O Paulo mencionou uma palavra muito importante: teste. Em vários cenários estamos envolvendo a aplicação Java e achamos que o erro é no código, e na verdade, é no Postman.

Se vier manualmente e digitar o endereço no Postman, ele já gera um erro. Por isso, é importante fazermos os testes e usar as ferramentas ao nosso favor para verificar e complementar o nosso trabalho como pessoa desenvolvedora.

Sobre o curso Java: consumindo API, gravando arquivos e lidando com erros

O curso Java: consumindo API, gravando arquivos e lidando com erros possui 161 minutos de vídeos, em um total de 56 atividades. Gostou? Conheça nossos outros cursos de Java em Programação, ou leia nossos artigos de Programação.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Requisições e respostas
• Utilizando uma biblioteca externa
• Lidando com exceções
• Persistindo dados em arquivos
• Consolidando conhecimentos