💌[안드로이드/코틀린] Retrofit 어노테이션(@)

📌 Retrofit 어노테이션(@)?

• Retrofit은 우리가 작성한 서비스 인터페이스에 따라 통신을 수행.
  결국 어떤 어노테이션(@)을 작성할지가 핵심.

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

• HTTP 메소드를 정의하는 어노테이션

// 경로를 지정하면 baseURL 뒤에 추가되어 최종 서버 요청 URL이 됨 
@GET("json/GetParkInfo/1/5")
    fun getParkInfo(): Call<ParkInfoModel>
    
// Call 객체 얻기
val call = service.getParkInfo()
    
// 최종 서버 요청 URL
http://openapi.seoul.go.kr:8088/json/GetParkInfo/1/5
    

💜 @Path

• URL 의 경로를 동적으로 지정해야 할 때.
  ex) json/GetParkInfo/1/5 또는 json/GetParkInfo/2/10
  동적으로 들어가는 부분을 중괄호{}로 감싸야 함.
• 들어갈 데이터를 함수의 매개변수로 받으려면 그 변수에 @Path 어노테이션 추가

// 경로를 지정하면 baseURL 뒤에 추가되어 최종 서버 요청 URL이 됨
@GET("json/GetParkInfo/{START_INDEX}/{END_INDEX}")
    fun getParkInfo(
        @Path("START_INDEX") startIndex: Int,
        @Path("END_INDEX") endIndex: Int
    ): Call<ParkInfoModel>
    
    
// Call 객체 얻기
val call = service.getParkInfo("2","10")

// 최종 서버 요청 URL
http://openapi.seoul.go.kr:8088/json/GetParkInfo/2/10

💜 @Query

• 경로에 ?를 이용해 데이터 전달해도 되지만, 함수의 매개변숫값을 서버에 전달하고 싶을 떄.
  ex) @Query("name") -> 서버 요청 시 name을 키로, 매개변숫값을 값으로 해서 데이터 전달.

// 경로에 ?를 이용해 데이터 전달
@GET("json/GetParkInfo/?name=soyoung&sort=age")
    fun getParkInfo(): Call<ParkInfoModel>

// @Query를 이용
@GET("json/GetParkInfo")
    fun getParkInfo(
        @Query("name") value1: String,
        @Query("sort") value2: String
    ): Call<ParkInfoModel>
    
 
// Call 객체 얻기
val call = service.getParkInfo("soyoung","age")

// 최종 서버 요청 URL
http://openapi.seoul.go.kr:8088/json/GetParkInfo/?name=soyoung&sort=age

💜 @QueryMap

• 전송할 데이터가 많을 때. (매개변수 여러개)
  전송할 데이터를 Map 타입으로 받기.

@GET("json/GetParkInfo")
    fun getParkInfo(
        @QueryMap values: Map<String,String>
    ): Call<ParkInfoModel>
    
 
// Call 객체 얻기
val call = service.getParkInfo("name" to "soyoung, "sort" to "age", "connect" to "phone")

// 최종 서버 요청 URL
http://openapi.seoul.go.kr:8088/json/GetParkInfo/?name=soyoung&sort=age&connect=phone

💜 @Body

• 전송할 데이터를 모델 객체로 지정하고 싶을 때.
  이 객체의 프로퍼티명-데이터(key-value) 로 JSON 문자열 만들어 전송.
  JSON 문자열은 데이터 스트림으로 전송하므로 @GET 에서는 사용 불가.
• @POST와 함께 사용 가능.
• 서버요청 URL은 바뀌지않음.
• JSON 문자열로 만들어 URL이 아닌 데이터 스트림으로 서버에 전송.

data class LoginRequest(
    val userId : String,
    val password : String
)


@POST("user/signin")
    fun requestLogin(
        @Body loginRequest: LoginRequest,
        @Query("sort") value: String
    ) : Call<LoginResponse>
    
    
// Call 객체 얻기    
val loginService = userService.requestLogin(LoginRequest("textId", "textPwd"),"age")

// 최종 서버 요청 URL
baseeURL/user/signin?sort=age

// 서버에 스트림으로 전송되는 데이터
{"userId":"textId","password":"textPwd"}
    

💜 @FormUrlEncoded , @Field

• @FormUrlEncoded : 데이터를 URL 인코딩 형태로 만들어 전송할 때.
  (@Body 는 JSON으로 만들어 전송.)
• @Field : 인코딩 될 데이터에 추가하는 어노테이션.
• @POST 방식에서만 사용 가능.

@FormUrlEncoded
@POST("user/signin")
    fun requestLogin(
        @Field userId: String,
        @Field password: String,
        @Query("sort") value: String
    ) : Call<LoginResponse>
    
    
// Call 객체 얻기    
val loginService = userService.requestLogin("textId", "textPwd","age")

// 최종 서버 요청 URL
baseeURL/user/signin?sort=age

// 서버에 스트림으로 전송되는 데이터
userId=textId&password=textPwd

• @Field 는 모델 객체에는 사용 불가
  -> 여러 데이터를 지정하려면 배열이나 List객체 사용.

@FormUrlEncoded
@POST("user/signin")
    fun requestLogin(
        @Field("name") names: List<String>
    ) : Call<LoginResponse>
    
    
// Call 객체 얻기    
val list: MutableList<String> = ArrayList()
list.add("so")
list.add("young")
val loginService = userService.requestLogin(list)

// 최종 서버 요청 URL
baseeURL/user/signin

// 서버에 스트림으로 전송되는 데이터
name=so&name=young

💜 @Header

• 헤더값 변경 시.

@Headers("Content-Type: application/json;charset=UTF-8")
@GET("json/GetParkInfo/1/5")
    fun getParkInfo(): Call<ParkInfoModel>

💜 @Url

• baseUrl을 무시하고 전혀 다른 URL을 지정할 때.

@GET
    fun getParkInfo(
        @Url url: String
    ): Call<ParkInfoModel>
    
    
// Call 객체 얻기    
val call = service.getParkInfo("http://openapi.seoul.go.kr")

// 최종 서버 요청 URL
http://openapi.seoul.go.kr