박민규

좋은 개발자가 되자

HTTP API를 만들어보자

다음과 같은 요구사항이 있다고 가정하자.

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

1. 회원 목록 조회
2. 회원 조회
3. 회원 등록
4. 회원 수정
5. 회원 삭제

그럼 위와 같은 요구사항을 만족하는 URI 설계는 어떻게 해야할까?

다음과 같이 설계할 수 있을 것이다.

1. 회원 목록 조회 /read-member-list
2. 회원 조회 /read-member-by-id
3. 회원 등록 /create-member
4. 회원 수정 /update-member
5. 회원 삭제 /delete-member

위와 같이 URI를 작성하는 것도 그럴듯해 보인다. 한 눈에 봐도 어떤 동작을 수행하는지 예측할 수 있기 때문이다. 하지만 위와 같이 URI를 설계하는 것은 바람직하지 못하다. 그 이유는 무엇일까? 바로 리소스 식별이다.

여기서 URI는 Uniform Resource Idetifier의 약자로, 보통 Uniform Resource Locator의 약자인 URL과 함께 비슷한 의미로 사용된다.

리소스 식별이란?

그렇다면 리소스의 의미는 무엇일까? 위의 예제를 예로 들면 리소스는 바로 회원이라는 개념 자체이다. 회원을 조회하고, 등록하고, 수정하고, 삭제하는 것은 행위로서 리소스와 상관 없는 것들이다. URI 설계를 할 때에는 회원이라는 리소스만 식별하면 된다. 다시 회원이라는 리소스에 집중해보자. URI를 어떻게 설계하는 것이 좋을까?

1. 회원 목록 조회 /members
2. 회원 조회 /members/{id}
3. 회원 등록 /members/{id}
4. 회원 수정 /members/{id}
5. 회원 삭제 /members/{id}

이번에는 URI를 리소스에 집중해 설계한 것을 볼 수 있다. 그런데 여기서 갸우뚱 하는 사람들이 생길 수 있고, 나도 처음 접할때는 그러했다. 다들 이렇게 생각할 수 있다. ‘그러면 같은 리소스에 대한 행위는 어떻게 구분하는거지?’ 바로 이것을 해결하기 위해 HTTP method가 존재하는 것이다.

HTTP method

주요 method

  • GET: 리소스 조회
  • POST: 요청 데이터 처리, 주로 등록에 사용
  • PUT: 리소스를 대체, 해당 리소스가 없으면 생성
  • PATCH: 리소스 부분 변경
  • DELETE: 리소스 삭제

위 5개의 method가 HTTP 주요 method이다. 다른 기타 method도 있으나, 크게 사용할 일이 없으니 알아만 두고 나중에 필요할 때 찾아보면 될 것 같다.

기타 method

  • HEAD: GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
  • OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
  • CONNECT: 대상 리소스로 식별되는 서버에 대한 터널을 설정
  • TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행

그럼 이제 우리는 리소스와 행위에 대해서 모두 알게되었다. 그럼 다시 위의 요구사항을 떠올려보며 REST API를 설계해보자.

최종 REST API 설계

1. 회원 목록 조회 GET /members
2. 회원 조회 GET /members/{id}
3. 회원 등록 POST /members/{id}
4. 회원 수정 PUT /members/{id}
5. 회원 삭제 DELETE /members/{id}

이제 우리는 URI에는 리소스를 정의하고, 그 행위를 정의하기 위해 HTTP method를 사용한다는 것을 알게 되었고 올바른 API 설계를 할 수 있게 되었다.

그러나 URI에 리소스만 담는것은 사실 굉장히 어렵고, 실제로는 최대한 리소스만 담고 어쩔 수 없는 경우에는 행위에 대한 내용도 URI에 포함된다.

참고 링크

모든 개발자를 위한 HTTP 웹 기본 상식

댓글남기기

참고