API URI 설계에서 가장 중요한 것은 리소스 식별이다.
리소스란?
회원을 조회/등록/수정/삭제 한다는 API 가 있다고 생각하자. 여기서 리소스란 조회/등록/수정/삭제가 아니라 회원이라는 개념 자체가 바로 리소스이다.
조회/등록/수정/삭제는 행위를 의미한다.
리소스와 행위를 분리해서 식별하여 URI를 설계하자.
EX)
- 조회 : /members/{id}
- 등록 : /members/{id}
- 수정 : /members/{id}
- 삭제 : /members/{id}
URI이 전부 같으면 어떻게 구분할것인가? (HTTP 메소드)
HTTP 메소드 종류
- GET : 리소스 조회
- POST : 요청 데이터 처리, 주로 등록에 사용
- PUT : 리소스를 대체, 해당 리소스가 없으면 생성
- PATCH : 리소스 부분 변경
- DELETE : 리소스 삭제
기타 메소드
- HEAD : GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
- OPTIONS : 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명 (CORS에 주로 사용)
- CONNECT : 대상 자원으로 식별되는 서버에 대한 터널을 설정
- TRACE : 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행
(CNNECT,TRACE)은 거의 사용하지 않는다.
GET
- 리소스를 조회
- 서버에 데이터를 쿼리 파라미터, 쿼리 스트링을 통해 전달
- 메시지 바디에 데이터를 넣어서 전송할 수 있지만, 중간 서버가 지원하지 않는곳이 많아서 권장하지 않음
POST
- 요청 데이터 처리
- 메시지 바디를 통해 서버로 요청 데이터 전달
- 서버는 요청 데이터를 처리 (메시지 바디를 통해 들어온 데이터를 처리하는 기능을 수행)
- 주로 데이터로 신규 리소스 등록, 프로세스 처리에 사용
- POST 메서드는 대상 리소스가 리소스의 고유 한 의미 체게에 따라 요청에 포함 된 표현을 처리하도록 요청합니다. EX(회원가입, 주문, 글쓰기, 댓글 달기)
- 다른 메서드로 처리하기 애매한 경우 (데이터를 바디에 넣어서 넘길때)
- 리소스 단위로 설계를 해야되지만 그렇지 못한경우는 컨트롤 URI로 사용해서 설계할수도 있음 EX(/members/{orderId}/delivery)
- POST는 모든것을 할 수 있다.
PUT
- 리소스를 대체
- 리소스가 있으면 대체
- 리소스가 없으면 생성
- 데이터를 덮어버림
- 클라이언트가 리소스를 식별 EX(/members/100)
PATCH
- 리소스 부분 변경
DELETE
- 리소스 제거
HTTP 메서더의 속성
- 안전(Safe Methods)
- 멱등(Idempotent Methods)
- 캐시가능(Cacheable Methods)
안전
- 호출해도 리소스를 변경하지 않는다 (GET, HEAD)
- 호출해서 변경이 일어나면 안전하지 않다
- 그외 부분에 장애는 고려하지 않는다.
멱등
- 한 번 호출하든 두번 호출하든 100번 호출하든 결과가 똑같아야한다.
- GET : 여러번 조회해도 같은 결과가 조회된다.
- PUT : 결과를 대체한다. 같은 요청을 여러번 해도 결과를 대체한다는 최종 결과는 같다.
- DELETE : 여러번 호출해도 삭제된 결과는 똑같다.
- POST : 멱등이 아니다. 프로세스가 두번이상 호출된다면 중복이 발생할 수 있다.
멱등 활용
- 자동 복구 메커니즘
- TIMEOUT등으로 정상 응답을 못했을때 클라이언트가 같은 요청을 해도 되는가?
멱등은 외부요인으로 인해 리소스가 변경되는거까지는 고려하지 않는다.
캐시가능
- 응답 결과 리소스를 캐시해서 사용해도 되는가?
- GET, HEAD, POST, PATCH 캐시가능
- 실제로는 GET, HEAD 정도만 캐시로 사용
- POST, PATCH는 본문 내용까지 캐시 키로 고려해야되서 구현이 쉽지않음.
참고자료
