[Android] Retrofit 서비스 인터페이스 정의 (애너테이션)

(출처 : 깡샘의 안드로이드 앱 프로그래밍 with 코틀린)

 

Retrofit을 이용하려면 네트워크 통신을 위해 호출할 함수를 포함한 서비스 인터페이스를 작성해야 한다.

interface INetworkService {
   @GET("api/users")
   fun doGetUserList(@Query("page") page: String): Call<UserListModel>
   @GET
   fun getAvatarImage(@Url url: String): Call<ResponseBody>
}

INetworkService라는 인터페이스명이나, doGetUserList나 getAvatarImage같은 함수명은 개발자가 지은 이름이다. 이 인터페이스를 구현하여 실제로 통신하는 클래스는 Retrofit이 자동으로 만들어주는데, 이때 @GET, @Query, @Url과 같은 애너테이션을 참조한다. 즉, 함수에 선언한 애너테이션을 보고 그 정보대로 네트워크 통신을 할 수 있는 코드를 자동으로 만들어 준다.

 

 

@GET, @POST, @PUT, @DELETE, @HEAD

이름대로 각 HTTP 메소드를 정의하는 애너테이션. 메소드명만 지정할 수도 있고 @GET("users/list") 처럼 URL 경로를 지정할 수 있다. 또, @GET("users/list?=sort desc")처럼 ?로 URL뒤에 데이터를 추가할 수 있다. 

//인터페이스에 선언한 함수
@GET("users/list?sort=desc")
fun test1() = Call<UserModel>

//Call 객체를 얻는 구문
val call: Call<UserModel> = networkService.test1()

//최종 서버 요청 url = https://reqres.in/users/list?sort=desc

 

@Path

URL의 경로를 동적으로 지정해야 할 때, 동적 영역에 들어갈 데이터를 함수의 매개변수로 받으려 사용하는 애너테이션.

이건 음.. 코드로 보면 이해가 빨리 되는 듯

//인터페이스에 선언한 함수
@GET("group/{id}/users/{name}")
fun test2(
	@Path("id") userId: String,
    @Path("name") arg2: String
): Call<UserModel>

//Call 객체를 얻는 구문
val call: Call<UserModel> = networkService.test2("10", "kkang")

//최종 서버 요청 URL = https://reqres.in/group/10/users/kkang

 

@Query

함수의 매개변수값을 서버에 전달하고 싶을 때 사용

//인터페이스에 선언한 함수
@GET("group/users")
fun test3(
	@Query("sort") arg1: String,
    @Query("name") arg2: String
): Call<UserModel>

//Call 객체를 얻는 구문
val call: Call<UserModel> = networkService.test3("age", "kkang")

//최종 URL = https://reqres.in/group/users?sort=age&name=kkang

 

@QueryMap

함수의 매개변수값을 여러개 선언하지 않고, Map 타입의 매개변수를 전달하고 싶을 때 사용

//인터페이스에 선언한 함수
@GET("group/users")
fun test4(
	@QueryMap options: Map<String, String>,
    @Query("name") name:String
): Call<UserModel>

//Call 객체를 얻는 구문
val call: Call<UserModel> = networkService.test4(
	mapOf<String, String>("one" to "hello", "two" to "world"),
    "kkang"
)

//최종 URL = httsp://reqres.in/group/users?one=hello&two=world&name=kkang

 

@Body

서버에 전송할 데이터를 모델 객체로 지정하여 보내고 싶을 때 사용. Body 값으로 선언한 매개변수는 모델 객체 타입이고, 이 객체의 프로퍼티명을 key로, 프로퍼티의 데이터를 값으로 해서 JSON문자열을 만들어 서버에 전송하게 된다.

//인터페이스에 선언한 함수
@POST("group/users")
fun test5(
	@Body user: UserModel,
    @Query("name") name: String
): Call<UserModel>

//Call 객체를 얻는 구문
val call: Call<UserModel> = networkService.test5(
	UserModel(id="1", firstName="gildong", lastName="hong", avatar="someurl"), "kkang"
)

//최종 URL = https://reqres.in/group/users?name=kkang
//서버에 전송된 데이터 {"id":"1", "first_name":"gildong", last_name":"hong", "avatar":"someurl"}

 

@Header

서버 요청에서 헤더값을 조정하고 싶을 때 사용한다. 간단하게 조정하고 싶은 헤더값을 기입해주면 된다. 

 

@Url

지정된 baseUrl을 무시하고 전혀 다른 URL을 지정하고 싶을 때 사용하는 애너테이션.