좋은 HTTP URI 설계

대표사진 정사각형으로 바꿨당

이 글은 김영한님 ‘모든 개발자를 위한 HTTP 웹 기본 지식’ 강의를 듣고 작성합니다.

[4. http 메서드] 강의에 해당된 내용을 정리하며 회고록을 작성합니다.

---

"개발자님, API 명세서 작성해주세요" "넵"

API 명세서를 작성하기 앞서, URI 설계를 어떻게 해야 잘한걸까?

 

좋은 HTTP API 설계

HTTP API를 설계할 때 고려해야 할 가장 중요한 것은 리소스 식별! 이다.

리소스의 의미는 뭘까?

다음과 같은 회원 정보를 관리하는 API를 만든다고 가정해보자

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

API URI 설계

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

이렇게 uri에 조회(read), 생성(create), 수정(update), 삭제(delete)가 들어가게 설계를 할 것인가!

API를 설계할 때, 2가지를 고려해야한다.

• 리소스의 의미는 뭘까?
  여기에서 리소스는 회원을 등록하고 수정하고 조회하는게 아니다!
  "미네랄을 캐라" 에서 리소스는 "미네랄"이다.

즉, "회원"이라는 개념 자체가 바로 리소스다.

• 리소스를 어떻게 식별하는게 좋을까?
  회원을 등록하고 수정하고 조회하는 것을 모두 배제하고 "회원"이라는 리소스만 식별하면 된다.

즉, 회원 리소스를 URI에 매핑!

 

좋은 API URI 설계

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

계층 구조상 상위 컬렉션으로 보고 복수 단어 사용을 권장한다. (member->members)

하지만 회원 조회, 등록, 수정, 삭제가 같은 URI로 되어 있는데, 어떻게 구별하지?라는 의문이 들 수 있다.

 

리소스와 행위를 분리

URI는 리소스만 식별한다. 리소스와 해당 리소스를 대상으로 하는 행위를 분리하는데,

• 리소스: 회원
• 행위 : 조회, 등록, 삭제, 변경

이런 식으로, 리소스는 명사, 행위는 동사로 구분한다.

 

하지만, 행위는 어떻게 구분을 할까??

바로 메소드로 구분을 한다!

좋은 HTTP API는 리소스를 식별하고, 리소스와 행위를 분리하여 설계한다. 리소스와 행위의 분리는 메소드로 구분한다.

 

💡정리💡

API URI 설계할 때, 리소스와 행위를 분리하여 설계한다.

URI는 리소스만 식별하고, 행위는 메소드로 구분을 한다.