좋은 REST API 설계 방법은? (개념/ 예제)

서론

---

이번 글에서는 어떻게 해야 좋은 REST API를 설계할 수 있는지에 대해 정리해보려한다. 진행방식은 설계 예시 시나리오를 만들어보고 HTTP(REST) Method를 설계해가는 방식으로 진행할 예정이다.

 

---

 

https://idratherbewriting.com/2015/08/28/all-about-rest-apis/

 

REST API 설계

---

[시나리오]

회원 정보 관리 API를 만들어보아라.

설계를 위해 회원 정보 관리에 관련된 API를 먼저 나열해보자.

 

 

 

[API 설계 목록]

• 회원 목록 조회
• 회원 조회
• 회원 등록
• 회원 수정
• 회원 삭제

기본적으로 위와 같이 5개로 추려볼 수 있다.

이것을 누구는 한눈에 알기 쉽게 아래와 같이 API URI를 설계할 수 있다.

 

 

 

[API URI 설계 초안]

• 회원 목록 조회  -->  /read-member-list
• 회원 조회  ------->  /read-member-by-id
• 회원 등록  ------->  /craete-member
• 회원 수정  ------->  /update-member
• 회원 삭제  ------->  /delete-member

 

위와 같이 기본적으로 적용해볼 수 있는데, 이것은 과연 좋은 방식일까?

 

답부터 말하면 아니다.

 

그 이유는 이전 포스팅에서 설명한 URI, URL의 포인트는 리소스이다. 이 HTTP API URI를 설계하면서 우리가 생각할 중요 포인트는 리소스 식별이다.

 

여기서 리소스는 무엇을 의미할까?

 

회원 관리 API에서는 바로 "회원"이 중요 리소스라 볼 수 있다. 회원을 등록하고 수정하고 조회하는게 리소스가 아닌 회원이라는 하나의 자원을 리소스라고 보는 것이 맞다.

 

회원을 등록하고 수정하고 조회하는것을 모두 배제하고, 회원이라는 리소스만 식별하면 되는 것이다. 이제 이 개념을 갖고 다시 URI를 설계해보자.

 

 

 

[좋은 API URI 설계]

• 회원 목록 조회  -->  /members
• 회원 조회  ------->  /members/{id}
• 회원 등록  ------->  /members/{id}
• 회원 수정  ------->  /members/{id}
• 회원 삭제  ------->  /members/{id}

 

위에서 설명한대로 올바른 설계를 하면 위와 같이 설계할 수 있다.

그런데!! CRUD의 API가 모두 똑같은데 이를 어떻게 구분하지?

 

질문의 답은 행위를 나누면 된다. 여기서 말하는 행위는 메서드를 말한다.

 

URI는 리소스만 식별하는 것이고, 해당 리소스를 대상으로 하는 행위(메서드)를 분리하여 설계를 하려는 것이다. 리소스는 명사(회원), 행위는 동사(등록/삭제하라)로 볼 수 있다.

 

물론 실무 현업에서 사용할 때 위와같이 리소스만 작성하고 메서드로 구분지을 수 없는 부분들도 있기에 항상 저렇게 해야 맞다는 내용은 아니다. 그렇지만, 위와 같이 기본적으로 리소스 식별을 기준으로 설계한다는 개념을 갖고 설계를 하냐 안하냐의 차이가 있기 때문에 가볍게 보고 넘어갈 것은 아니다.

 

 

 

[HTTP 메서드 종류]

• GET
• POST
• PUT
• PATCH
• DELETE

 

많이 사용 되는 5가지 메서드를 나열해봤는데 각각 개념은 추 후 하나씩 알아보도록 하겠다.

 

---

 

참고..

---

1. members라고 표현한 이유는 계층 구조상 상위를 컬렉션으로 보기 때문에 이럴 경우 복수단어를 사용한다.

 

2. 보통 http api를 rest api로 부르는 경우가 있고 두 개를 구분짓고 말하지 않지만 알고보면 두 개는 엄격하게는 다르다고한다. 추 후 이 두개의 관계에 대해 정리해본다면 추가 링크를 달아놓겠다.