android-retrofit

Android Networking with Retrofit

Instructions

When implementing network layers using Retrofit, follow these modern Android best practices (2025).

1. URL Manipulation

Retrofit allows dynamic URL updates through replacement blocks and query parameters.

• Dynamic Paths: Use {name} in the relative URL and @Path("name") in parameters.
• Query Parameters: Use @Query("key") for individual parameters.
• Complex Queries: Use @QueryMap Map<String, String> for dynamic sets of parameters.

interface SearchService {
    @GET("group/{id}/users")
    suspend fun groupList(
        @Path("id") groupId: Int,
        @Query("sort") sort: String?,
        @QueryMap options: Map<String, String> = emptyMap()
    ): List<User>
}

2. Request Body & Form Data

You can send objects as JSON bodies or use form-encoded/multipart formats.

• @Body: Serializes an object using the configured converter (JSON).
• @FormUrlEncoded: Sends data as application/x-www-form-urlencoded. Use @Field.
• @Multipart: Sends data as multipart/form-data. Use @Part.

interface UserService {
    @POST("users/new")
    suspend fun createUser(@Body user: User): User

    @FormUrlEncoded
    @POST("user/edit")
    suspend fun updateUser(
        @Field("first_name") first: String,
        @Field("last_name") last: String
    ): User

    @Multipart
    @PUT("user/photo")
    suspend fun uploadPhoto(
        @Part("description") description: RequestBody,
        @Part photo: MultipartBody.Part
    ): User
}

3. Header Manipulation

Headers can be set statically for a method or dynamically via parameters.

• Static Headers: Use @Headers.
• Dynamic Headers: Use @Header.
• Header Maps: Use @HeaderMap.
• Global Headers: Use an OkHttp Interceptor.

interface WidgetService {
    @Headers("Cache-Control: max-age=640000")
    @GET("widget/list")
    suspend fun widgetList(): List<Widget>

    @GET("user")
    suspend fun getUser(@Header("Authorization") token: String): User
}