Utilizando Retrofit no Android

Neste primeiro post vamos criar um aplicativo simples que acessa uma API pública utilizando a biblioteca Retrofit.

Introdução

Retrofit é uma biblioteca muito utilizada no mundo Android para facilitar o trabalho de fazer requisições utilizando o protocolo HTTP. Mais informações podem ser encontradas no próprio site da biblioteca: http://square.github.io/retrofit/

O que iremos desenvolver

Nesse primeiro exemplo iremos desenvolver um aplicativo bem simples, basicamente o que ele faz é receber um CEP e desenvolver o endereço correspondente. Para isso, acessaremos uma API chamada Postmon. Todas as informações relacionadas a API podem ser encontradas no site: http://postmon.com.br/.

A API funciona da seguinte forma, você passa um CEP para o endpoint http://api.postmon.com.br/v1/cep/*cep_aqui* e recebe como resposta um arquivo JSON com as informações referentes ao CEP informado.

Exemplo

Fazendo uma requisição do tipo GET para o endereço  http://api.postmon.com.br/v1/cep/49032490

Nos retorna o seguinte arquivo JSON:

Com essas informações já podemos começar a utilizar a Retrofit para consumir esse endpoint.

---

Antes de começar, precisamos importar a biblioteca para dentro do nosso projeto Android. Coloque as seguintes dependência no seu arquivo build.gradle:

compile 'com.squareup.retrofit2:retrofit:2.0.0'
compile 'com.squareup.retrofit2:converter-gson:2.0.0'

A razão de importar a biblioteca Gson é porque a Retrofit usa esse converter internamente para fazer o parsing do arquivo JSON. Gson não é o único converter compatível com a Retrofit. Segue abaixo alguns outros:

• Gson: com.squareup.retrofit2:converter-gson
• Jackson: com.squareup.retrofit2:converter-jackson
• Moshi: com.squareup.retrofit2:converter-moshi
• Protobuf: com.squareup.retrofit2:converter-protobuf
• Wire: com.squareup.retrofit2:converter-wire
• Simple XML: com.squareup.retrofit2:converter-simplexml

Também precisamos pedir a permissão de internet ao usuário, por isso coloque a seguinte permissão no seu AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>

Após isso, precisamos criar a classe modelo que servirá para representar esse objeto JSON. Como esse é um exemplo pequeno, só precisaremos do bairro, cidade e logradouro referentes ao CEP informado.

public class Endereço {
    private String bairro;
    private String cidade;
    private String logradouro;

    // respectivos getters e setters
}

Como a Retrofit funciona?

A biblioteca transforma a sua API (No nosso caso a Postmon API) em uma interface Java. Após isso, ela gera uma classe que implementa essa interface e com isso, ao chamar os métodos da classe, as requisições serão realizadas.

No seu projeto, crie uma interface que servirá para fazer representar a API.

public interface PostmonService {
    @GET("{cep}")
    Call<Endereço> getEndereco(@Path("cep") String cep);
}

Como você pode ver, criei um método abstrato que recebe um CEP como parâmetro (lembra do CEP na URL do endpoint?) e retorna um objeto Call tipado com a nossa classe modelo. É através desse objeto Call que faremos a requisição HTTP. Com a anotação @GET(“{cep}”) a biblioteca vai concatenar a URL Base do endpoint com o @Path(“cep”), gerando assim a nossa URL.

---

O aplicativo terá uma interface bem simples, basicamente um EditText onde o usuário digitará o CEP, um Button para enviar os dados e um TextView para mostrar os dados retornados pela API.

Agora na sua activity, criaremos um objeto Retrofit que servirá para inicializar o serviço

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("http://api.postmon.com.br/v1/cep/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
}

No objeto Retrofit podemos perceber duas coisas. Você precisa chamar o método baseUrl(String) que é a parte estática do seu endpoint, ou seja, a parte que não muda. E você também precisa informar qual converter você usará para a biblioteca fazer o parsing do JSON retornado.

Agora a Retrofit precisa criar uma classe que implementa a interface que criamos, para isso, crie o seguinte objeto:

PostmonService service = retrofit.create(PostmonService.class);

Pode parecer estranho mas nós não estamos instanciando a interface PostmonService e sim criando uma classe que a implementa.

Com esse objeto, agora podemos fazer a chamada dos métodos contidos na interface:

Call<Endereço> call = service.getEndereco(cep);

O “cep” é o texto do EditText. Já sabemos que o método getEndereco() nos retorna um objeto Call<Endereco>, é através desse objeto que iremos realizar a requisição HTTP. Existem duas maneiras de fazer essa chamada, síncronamente ou assíncronamente. No Android não é permitido executar operações que demandam muito tempo, como por exemplo, uma requisição HTTP, na UI Thread, pois pode ocasionar o travamento da aplicação. Por isso faremos uma chamada assíncrona utilizando o método enqueue(Callback) da classe Call.

call.enqueue(new Callback<Endereço>() {
    @Override
    public void onResponse(Call<Endereço> call, Response<Endereço> response) {
        if (response.isSuccessful()) {
            Endereço endereço = response.body();

            String strEndereço = "Cidade: " + endereço.getCidade() + "\n" +
                    "Bairro: " + endereço.getBairro() + "\n" +
                    "Logradouro: " + endereço.getLogradouro();

            tvDados.setText(strEndereço);
        }
    }

    @Override
    public void onFailure(Call<Endereço> call, Throwable t) {
        Toast.makeText(MainActivity.this, 
                       "Não foi possível realizar a requisição",
                       Toast.LENGTH_SHORT).show();
    }
});

Essa função recebe um Callback que será executado assim que a requisição for finalizada. Esse Callback contém dois métodos, onResponse() e onFailure(). Caso o onResponse() seja chamado, isso significa que a requisição obteve uma resposta. Caso o onFailure() seja chamado, significa que a requisição não obteve êxito.

Obter uma resposta não significa que você recebeu o que queria, pois isso é necessário verificar se a resposta obteve êxito, através do método isSuccessful(). 

No onResponse()  você tem acesso ao corpo da resposta através do método body(). É lá que está o nosso objeto Endereço já deserializado. Com acesso a ele, você pode fazer o que quiser, no nosso caso, estamos apenas imprimindo os dados na tela.

O resultado é o seguinte:

Todo o código do exemplo acima se encontra no GitHub: https://github.com/froesmatheus/exemplo-retrofit