Retrofit para Kotlin: guia completo com exemplos

O que é Retrofit e para que serve?

\n\n

Retrofit é um cliente HTTP tipicamente seguro para Java e Kotlin, desenvolvido pela Square. É uma das bibliotecas mais populares para trabalhar com APIs REST no ecossistema Android. Retrofit permite que desenvolvedores executem requisições HTTP para servidores remotos de forma fácil e elegante, convertendo automaticamente respostas JSON em objetos Kotlin e vice-versa.

\n\n

Para que serve o Retrofit?

\n

\n
• Simplificação do trabalho com APIs: Em vez de escrever código extenso com HttpURLConnection ou OkHttp, você define uma interface com anotações, e o Retrofit gera a implementação automaticamente.
\n
• Serialização/desserialização automática: Graças à integração com conversores (Gson, Moshi, Kotlinx Serialization), o Retrofit converte automaticamente JSON em objetos Kotlin.
\n
• Suporte a diversos métodos HTTP: GET, POST, PUT, DELETE, PATCH, HEAD e OPTIONS.
\n
• Gerenciamento de cabeçalhos e parâmetros: Fácil adicionar cabeçalhos dinâmicos ou estáticos, parâmetros de consulta e parâmetros de caminho.
\n
• Assincronicidade: Suporte a corrotinas Kotlin (funções suspend) e interfaces de Callback.
\n
• Integração com OkHttp: Retrofit usa OkHttp como motor HTTP, dando acesso a poderosos recursos de interceptação de requisições (interceptors).
\n

\n\n

Retrofit é ideal para aplicativos Android que interagem com serviços web RESTful: desde aplicativos meteorológicos simples até redes sociais complexas.

\n\n

Instalação do Retrofit em um projeto Kotlin

\n\n

Ao contrário do Python (onde se usa pip), em projetos Kotlin/Android as dependências são gerenciadas via Gradle. Adicione as seguintes linhas ao arquivo build.gradle.kts (ou build.gradle) do seu módulo (geralmente app):

\n\n

// build.gradle.kts (Module :app)\ndependencies {\n    // Biblioteca principal do Retrofit\n    implementation("com.squareup.retrofit2:retrofit:2.9.0")\n    \n    // Conversor para trabalhar com JSON (Gson)\n    implementation("com.squareup.retrofit2:converter-gson:2.9.0")\n    \n    // Conversor alternativo (Moshi)\n    // implementation("com.squareup.retrofit2:converter-moshi:2.9.0")\n    \n    // Para suporte a corrotinas (funções suspend)\n    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")\n    \n    // OkHttp (geralmente já incluído, mas pode ser adicionado explicitamente)\n    implementation("com.squareup.okhttp3:okhttp:4.12.0")\n    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")\n}\n

\n\n

Importante: Após adicionar as dependências, clique em "Sync Now" no Android Studio para baixar as bibliotecas.

\n\n

Início rápido: exemplo de código

\n\n

Vamos criar um aplicativo simples que obtém uma lista de posts do JSONPlaceholder (API de teste gratuita).

\n\n

Passo 1: Crie uma data class para a resposta

\n\n

data class Post(\n    val userId: Int,\n    val id: Int,\n    val title: String,\n    val body: String\n)\n

\n\n

Passo 2: Defina a interface da API

\n\n

interface ApiService {\n    @GET("posts")\n    suspend fun getPosts(): List<Post>\n    \n    @GET("posts/{id}")\n    suspend fun getPostById(@Path("id") postId: Int): Post\n}\n

\n\n

Passo 3: Crie o cliente Retrofit

\n\n

object RetrofitClient {\n    private const val BASE_URL = "https://jsonplaceholder.typicode.com/"\n    \n    val instance: ApiService by lazy {\n        Retrofit.Builder()\n            .baseUrl(BASE_URL)\n            .addConverterFactory(GsonConverterFactory.create())\n            .build()\n            .create(ApiService::class.java)\n    }\n}\n

\n\n

Passo 4: Use na Activity ou ViewModel

\n\n

class MainActivity : AppCompatActivity() {\n    override fun onCreate(savedInstanceState: Bundle?) {\n