Retrofit2) Retrofit2 API 정의 기초

이 포스팅은 https://futurestud.io/tutorials/retrofit-2-basics-of-api-description 블로그를 참조하여 작성했습니다.(거의 번역해서 정리한 수준) :D

어떻게 API를 정의할 것인가?

public interface GitHubClient { @GET("/users/{user}/repos") Call<List<GitHubRepo>> reposForUser( @Path("user") String user ); }

위의 코드를 보시면 전에 했던 예제를 볼 수 있습니다.

이번 포스팅은 Retrofit2 API Interface를 정의를 하는 기초적인 방법을 알아볼 것입니다.

1. HTTP Method

서버와 클라이언트간 통신을 하기 위해 HTTP 프로토콜을 사용합니다.

HTTP 프로토콜에 관한 내용은 HTTP 프로토콜 관련 문서를 참조해주시길 바랍니다.

참조 문서 : https://www.joinc.co.kr/w/Site/Network_Programing/AdvancedComm/HTTP

HTTP프로토콜 메소드는

GET(참조)

POST(추가)

PUT(수정)

DELETE(삭제)

등이 있습니다. 이러한 메소드들을 우리는 @(어노테이션)을 사용해서 

@GET,@POST, @PUT, @DELETE, @HEAD or @PATCH 를 사용할 수 있습니다. 

즉 간편하게 다음과 같이 어노테이션으로 HTTP 메소드를 구현할 수가 있습니다.

public interface FutureStudioClient { @GET("/user/info") Call<UserInfo> getUserInfo(); @PUT("/user/info") Call<UserInfo> updateUserInfo( @Body UserInfo userInfo ); @DELETE("/user") Call<Void> deleteUser(); }

2. HTTP 자원 위치 경로

@GET("/user/info") 처럼 @GET, @POST, @PUT, @DELETE 안에 우리가 접근하고자 하는 위치 경로를 설정해 줄 수가 있습니다.

하지만 위치 설정을 할 때 @GET("http://futurestud.io/api/user/info")같이 풀 URL로 작성하는 것을 지양해야합니다.

왜냐하면. base URL(기본 URL: http://futurestud.io)을 변수로 지정해서 각각 메소드는 ("/api/user/info")이렇게 접근하는 장점이 있기 때문입니다.

public interface FutureStudioClient { @GET("/user/info") Call<UserInfo> getUserInfo(); @PUT("/user/info") Call<UserInfo> updateUserInfo( @Body UserInfo userInfo ); @DELETE("/user") Call<Void> deleteUser(); // example for passing a full URL @GET("https://futurestud.io/tutorials/rss/") Call<FutureStudioRssFeed> getRssFeed(); }

3. 함수 이름과 리턴 타입

Call<UserInfo> getUserinfo(); 에는 3개의 부분이 있습니다.

1. 메소드의 이름

2. 메소드의 리턴 타입

3. 메소드의 매개변수

등으로 나눌 수가 있습니다.

먼저 메소드 이름은 사용하기에 적당한 이름을 적어줍니다. 어떠한 이름을 사용해도 상관이 없습니다.

Call<UserInfo>는 리턴 타입을 뜻합니다. 리턴 타입은 무조건 있어야기 때문에 적어주어야됩니다.

리턴 타입은 서버로 부터 데이터의 종류를 생각해서 클래스를 정의해야 됩니다.

Call<UserInfo>에서 UserInfo 클래스는 유저 데이터를 가지고 있다고 생각할 수 있습니다. 그리고 

프로그래머가 직접 파징할 필요없이 Retrofit이 자동으로 데이터를 파징할 수 있습니다.

만약 파징한 데이터타입이 아니라 JSON 타입으로 원래 데이터를 받기를 원한다면 ResponseBody 클래스를 사용하면 됩니다.

그리고 응답을 받을 필요가 없을 시엔 Call<Void>처럼 Void 형을 사용해주면 됩니다.

매개변수는 많은 옵션들이 있는데, 여기서 3가지의 옵션을 살펴보겠습니다.

@Body: 응답 내용으로 자바객체를 보냅니다.

@Url : 동적 URL을 사용합니다.

@Field : 형식화된 인코딩된 url로써 데이터를 보냅니다.

public interface FutureStudioClient { @GET("/user/info") Call<UserInfo> getUserInfo(); @PUT("/user/info") Call<Void> updateUserInfo( @Body UserInfo userInfo ); @GET Call<ResponseBody> getUserProfilePhoto( @Url String profilePhotoUrl ); }

4. Path 매개변수

REST API은 동적 URL으로 만들어졌습니다. URL의 각각 경로를 동적으로 접근이 가능한데.

예를 들면 http://futurestud.io/api/tutorials/3 에서 3부분을 2나 1처럼 원하는 경로를 동적으로 접근이 가능합니다.

우리가 예전 포스팅에서 다뤘던

public interface GitHubClient { @GET("/users/{user}/repos") Call<List<GitHubRepo>> reposForUser( @Path("user") String user ); }

처럼 다루면 됩니다.

{user}는 동적인 URL 값이 위치하는 곳이라는 뜻입니다. 여기에 @Path의 매개변수를 전해주면 그 자리에 매개변수 값이 전해집니다.

그리고 Path 매개변수는 몇번 사용해도 상관이 없습니다.

5. Query 매개변수

https://futurestud.io/tutorials?filter=video

여기서 ?filter=video 처럼 어느 데이터를 요청하는지 설명하는 query 문이 있습니다. 위 쿼리를 요청하기위해서

직접 주소창에 쓸 필요가 없이 @Query 매개변수를 사용하면됩니다.

@Query() 안에 매개변수는 query의 이름이고 메소드의 매개변수는 query의 값을 의미합니다. Retrofit은 자동으로 query를 설정해서 응답해줍니다.

만약 메소드 값에 null을 입력하면 Retrofit은 그냥 무시해버립니다 .

public interface FutureStudioClient { @GET("/tutorials") Call<List<Tutorial>> getTutorials( @Query("page") Integer page ); @GET("/tutorials") Call<List<Tutorial>> getTutorials( @Query("page") Integer page, @Query("order") String order, @Query("author") String author, @Query("published_at") Date date ); }