HTTP - HTTP API 설계와 HTTP메서드

들어가며

• HTTP 메서드를 알아보기 이전에 기본적인 API에 대한 URL설계에 대해 한번 논의해본다.

 

 

 

API URI 설계

• 만약의 예시를 들어 회원 정보를 관리하는 API를 만들어야 한다고 가정하자.
• 회원 정보를 관리하기 위해서는 다음과 같은 기능들이 필요하다.
  • 회원 전체 목록 조회
  • 회원 조회
  • 회원 등록
  • 회원 수정
  • 회원 삭제
• 그리고 각 기능에 대해 URI를 지정해줘야 할 것이다. 그래야 그 경로로 요청이 가서 서버에서 그 요청에 맞는 로직을 수행할 수 있을 것이다.
• 각 기능을 그대로 URI에 옮긴 경로는 다음과 같을 것이다.
  • 회원 목록 조회 - /read-member-list
  • 회원 조회 - /read-member-by-id
  • 회원 등록 - /create-member
  • 회원 수정 - /update-member
  • 회원 삭제 - /delete-member
• 문제는 이렇게 설계한 URI가 과연 좋은 설계라고 할 수 있는가에 대해서이다. URI에 대한 정의를 다시 가져와 살펴보도록 하자.
  • URI는 어떤 자원을 다른 자원들과 구분하기 위해 만든 개념
  • 이때 자원은 식별할 수 있는 모든 것(thing)
• 생각해보면 회원 목록을 조회하고, 등록하는 동작이 리소스가 아니라는 것을 알 수 있다. 리소스는 바로 그 동작의 대상인 회원 그 자체이다.
• 회원 관리 URI는 회원이라는 리소스를 식별하기 위해 만들어야 하므로 회원 리소스를 URI에 매핑시켜야 한다. 즉 동작에 초점을 두지 말고, 그 동작의 대상에 초점을 맞추어야 한다.
• 이제 "회원" 이라는 리소스에 초점을 맞추어 생각해보자. 먼저 회원 목록 조회이다.
  • 회원 목록 조회는 회원들의 리스트를 조회하는 것이다. 즉 회원들(members)의 정보를 나열하는 것이다. 이것을 생각하면 /members로 하는 것이 좋아보인다.
• 이후에는 회원 조회이다.
  • 회원 조회는 회원들(members)중 특정 개체(id)를 찾아 그 회원의 정보를 보는 것이다. URI는 계층형 구조이므로 members가 회원들의 집합 디렉토리라고 생각한다면 그 members의 내부에 회원의 id로 식별이 가능할 것이다.
  • id 이외에 다른 것으로 식별이 가능할 수도 있지 않는가 라고 할 수 있다. 하지만 생각해보자. 회원의 이름과, 나이, 성별조차도 모두 동일하다면 기본적인 정보로 구분하기가 쉽지 않을 것이다.
  • 따라서 회원 한명을 조회하는 것은 /members/{memberId}로 생각해보는게 좋다.
• 이제 문제는 이 다음부터이다.
  • 회원을 등록하는 것은 어떻게 해야할까? 회원 등록은 해당 회원의 신규 id를 발급받아 회원 정보 저장소에 넣어야 한다는 것을 의미한다.
  • 즉 한 명의 회원을 회원들의 집합(members)에 넣어주어야 한다. 일상적으로 비유하자면 어떤 폴더에 새로운 파일을 집어넣는것과 같다.
  • 그렇다면 역시 등록 URI도 /members/{memberId}로 생각하는게 좋아 보인다.

 

 

 

리소스 중점 설계의 문제점

• 문제는 위에서 회원 조회와 등록의 URI가 동일하게 /members/{memberId}라는 것이다.
• URI가 동일한데 서로 다른 동작을 처리하게 해야 한다. 이는 회원 정보를 수정하는 것과, 회원 정보를 삭제하는 것 역시 마찬가지다.
• 둘 다 회원들의 정보가 모여 있는 일종의 폴더 내부에서 해당 회원의 id를 이용해 찾고 수정하거나, 삭제해야 하므로  URI가 동일하게 /members/{memberId}가 되는 것이다.
• 이를 모두 적용하면 다음과 같은 URI들이 완성된다.
  • 회원 목록 조회 - /members
  • 회원 조회 - /members/{memberId}
  • 회원 등록 - /members/{memberId}
  • 회원 수정 - /members/{memberId}
  • 회원 삭제 - /members/{memberId}
• 해당 설계는 리소스인 회원(members)에 대해서는 잘 식별할 수 있는 URI 설계이다. 리소스와 리소스를 대상으로 하는 어떠한 행위들을 잘 분리시켰기 때문이다.
• 그런데 이러한 행위들을 어떻게 구분해야 하는가에 대한 문제점이 생긴다. 위의 URI만 봐서는 도대체 어떤 행위를 리소스에게 수행하려고 하는지 알 수 없다.

 

 

 

HTTP Method

• 행위를 구분하는 것을 이제 HTTP Method로 구분할 수 있다. HTTP 메서드는 GET, POST, PATCH, PUT, DELETE로 각각 조회, 등록, 수정, 수정, 삭제를 나타낸다.
• 다음 포스트에서 해당 메서드들에 대한 상세한 특성을 살펴보도록 하겠다.