Definición del contrato de red con Retrofit¶

1. El concepto de contrato API¶

En Retrofit, la API se define como un contrato mediante una interfaz.
Este contrato especifica: - Qué endpoint se consume - Qué método HTTP se usa - Qué parámetros se envían - Qué tipo de respuesta se espera

La implementación real la genera Retrofit automáticamente.

2. Anotaciones principales de Retrofit¶

Retrofit utiliza anotaciones para describir las peticiones.

2.1. Métodos HTTP¶

@GET
@POST
@PUT
@DELETE

Ejemplo conceptual:

@GET("users")
suspend fun getUsers(): Response<List<User>>

3. Parámetros en Retrofit¶

3.1. Parámetros de ruta (`@Path`)¶

Se usan cuando parte de la URL es variable.

@GET("users/{id}")
suspend fun getUserById(@Path("id") id: Int): Response<User>

3.2. Parámetros de consulta (`@Query`)¶

Se añaden al final de la URL.

@GET("users")
suspend fun search(@Query("name") name: String): Response<List<User>>

4. Respuestas y envoltorio Response¶

Retrofit puede devolver directamente el objeto o envolverlo en Response<T>.

Ventajas de usar Response<T>: - Acceso al código HTTP - Acceso a cabeceras - Comprobación de éxito (isSuccessful)

if (response.isSuccessful) {
    val data = response.body()
}

5. Manejo de errores¶

Errores habituales: - Error HTTP (404, 500…) - Respuesta vacía - Error de red (sin conexión)

Por eso nunca se debe asumir que body() es no nulo.