HTTP API의 올바른 설계 방법

출처: 데브경수

처음 API URL을 설계하다보면 정말 이게 Best Practice인지 더 나은 방법이 없는지 끊임없이 고민했던 것 같습니다.

회원  API 메서드 설계 -1

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

과연 위와 같이 설계하는 방법이 best practice일까??

API URL을 설계할 때 리소스의 식별이 가장 중요합니다.위에 예시에서 회원을 조회, 삭제, 수정, 등록하는 게 리소스가 아닙니다. 회원이라는 개념 자체가 리소스입니다.

그러면 리소스를 어떻게 식별하는 게 좋을까?

회원을 등록, 수정, 조회하는 것을 모두 배제합니다. 회원이라는 리소스만 식별하면됩니다. -> 회원 리소스를 URL에 매핑

---

위에 내용을 적용해서 다시 설계한다면

회원  API 메서드 설계 -2

• 회원 목록 조회 GET:/members
• 회원 조회 GET:/members/{id}
• 회원 등록 POST:/members
• 회원 수정 PATCH, PUT, POST:/members/{id}
• 회원 삭제 DELETE/members/{id}

리소스와 행위를 분리해야합니다. 

리소스 -> 회원

행위 -> 조회, 삭제, 등록, 변경 (HTTP 메서드로 분리 가능)

 

최대한 리소스로만으로 설계하되, 어쩔 수 없는 경우 컨트롤 url(동사 사용)를 사용합니다.

ex) POST /orders/{oderId}/start-delivery -> (배달 시작) 동사를 사용해서 설계할 수 있다.

 

HTTP 메서드 종류

• GET: 리소스 조회 (메시지 바디를 이용해서 데이터를 전달 할 수있지만,(권장x) 쿼리 파리미터나 쿼리 스트링으로 전달)
• POST: 요청 데이터 처리, 주로 등록에 사용
• PUT: 기존 리소스를 완전히 대체, 해당 리소스가 없으면 생성, 덮어쓰기, 클라이언트가 리소스를 긱별
• PATCH: 리소스 부분 변경
• DELETE: 리소스 삭제

HTTP 메서드의 속성

멱등성(Idempotent) -> 한 번 호출하든 100번 호출하든 결과가 똑같아야 합니다.

멱등 메서드 

• GET : 요청이 반복되어도 같은 결과가 조회
• PUT : 결과를 대체합니다. 즉, 같은 요청을 여러 번 해도 마지막 결과는 똑같습니다.
• DELETE : 결과를 삭제합니다. 즉, 같은 요청을 여러번해도 이미 삭제된 결과는 같습니다.
• POST : 멱등성을 가지고 있지 않습니다. 두 번 호출하면 같은 로직이 중복해서 발생할 수 있습니다.

 

Q. 만약 재요청 중간에 다른 곳에서 리소스를 변경해버리면??

1. 사용자 1 요청 GET -> menu ="아메리카노"

2. 사용자 2 요청 PUT -> menu ="스무디"

3. 사용자 1 요청 GET -> menu="스무디" (사용자 2의 영향으로 바뀐 데이터 조회)

A. 위와 같은 상황처럼, 멱등은 외부 요인(다른 사용자)으로 중간에 리소스가 변경되는 것까지 고려하지 않습니다.