1. HTTP API를 만들어보자
요구사항에 따라 API URI 설계하기
a. 리소스 식별 및 URI 계층 구조 활용
회원 목록 조회 /members
회원 조회 /members/{id}
회원 등록 /members/{id}
회원 수정 /members/{id}
회원 삭제 /members/{id}
참고: 계층 구조상 상위를 컬렉션으로 보고 복수단어 사용 권장
b. 리소스와 행위를 분리
URI는 리소스만 식별한다.
따라서 리소스(= 회원; 명사)와 해당 리소스를 대상으로 하는 행위(= 조회, 등록, 삭제, 변경; 동사)를 분리해야 한다.
행위 구분은 HTTP 메서드를 활용한다.
HTTP 메서드 종류
a. 주요 메서드
- GET: 리소스 조회 - 회원 조회
- POST: 요청 데이터 처리 (주로 등록에 사용) - 회원가입, 로그인
- PUT: 리소스를 대체, 해당 리소스가 없으면 생성 - 회원 정보 전체 수정 or 회원가입, 로그인
- PATCH: 리소스 부분 변경 - 회원 정보 일부 수정
- DELETE: 리소스 삭제 - 회원 삭제
b. 기타 메서드 (참고만 하기)
- HEAD: GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
- OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명 (주로 CORS에서 사용)
- CONNECT: 대상 리소스로 식별되는 서버에 대한 터널을 설정
- TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행
2. HTTP 메서드 - GET, POST
GET
서버에 전달하고 싶은 데이터는 query parameter(string)으로 전달
메시지 바디를 통해 데이터를 전달(POST와 비슷)할 수 있지만 지원하지 않는 곳이 많아 권장하지 않음
POST
클라이언트가 메시지 바디를 통해 서버로 요청 데이터를 전달함
서버는 메시지 바디를 통해 들어온 요청 데이터를 처리하는 모든 기능을 수행함
보통 서버 개발자가 API 명세서를 바탕으로 Controller에 RequestMapping을 통해 요청마다 어떻게 처리할지 결정함
주로 전달된 데이터로 신규 리소스 등록, 프로세스 처리에 사용함
- 새 리소스 생성(등록)
- 서버가 아직 식별하지 않은 새 리소스 생성
- 요청 데이터(프로세스) 처리
- 데이터 생성과 변경 이외에 프로세스를 처리해야 하는 경우 (진행)
- ex. 주문에서 '결제완료 -> 배달시작 -> 배달완료'처럼 값의 변경을 넘어 프로세스의 상태가 변경되는 경우
- POST의 결과로 새로운 리소스가 생성되지 않을 수 있음
- ex. POST /orders/{orderId}/start-delivery
- Control URI: 명사만 쓰기 어려운 경우 동사를 사용해도 됨
- 데이터 생성과 변경 이외에 프로세스를 처리해야 하는 경우 (진행)
- 다른 메서드로 처리하기 애매한 경우
- ex. JSON으로 조회 데이터를 넘겨야 하는데, GET 메서드를 사용하기 어려운 경우
3. HTTP 메서드 - PUT, PATCH, DELETE
PUT
리소스가 있으면 완전히 대체, 없으면 생성
- 주의! 한 필드에 대한 데이터만 보내도 해당 데이터에 있는 모든 기존 값이 없어지고 그 필드 값만 저장돼버림
- 수정으로 사용해서는 안됨
클라이언트가 리소스를 식별함
- 클라이언트가 리소스 위치를 알고 URI를 지정 (ex. /members/100)
- POST와 차이점이라고 할 수 있음
PATCH
위에서 PUT으로는 데이터 대체만 가능했으나, PATCH를 사용하면 원하는 필드 값만 수정할 수 있음
PATCH를 지원하지 않는 서버라면 POST를 이용하면 됨
DELETE
리소스 제거 메서드
4. HTTP 메서드의 속성
안전(Safe Methods)
호출해도 리소스를 변경하지 않음
- GET은 조회용이라 안전하지만, 이외 메서드는 변경이 일어나기 때문에 안전하지 않음
로그가 쌓여서 장애가 발생하더라도 고려하지 않고, 해당 리소스만 고려함
멱등(Idempotent Methods)
한 번 호출하든 여러 번 호출하든 결과가 동일함
- GET: 모두 같은 결과가 조회됨
- PUT: 결과를 대체하기에 여러 번 요청해도 최종 결과가 같음
- DELETE: 결과를 삭제하기에 여러 번 요청해도 삭제된 결과가 같음
- POST: 멱등 X; 중복 발생은 오류로 이어질 수 있음
활용
- 자동 복구 메커니즘
- 서버가 TIMEOUT 등으로 정상 응답을 못 주었을 때, 클라이언트가 같은 요청을 다시 해도 되는가? 판단 근거
외부 요인으로 중간에 리소스가 변경되는 것까진 고려하지 않음
캐시 가능(Cacheable Methods)
응답 결과 리소스를 캐시에서 사용해도 되는가?
- GET, HEAD, POST, PATCH는 가능함
- 실제로는 GET, HEAD 정도만 (URI) 캐시로 사용하며, POST와 PATCH는 본문 내용까지 캐시 키로 고려해야 하기 때문 구현이 쉽지 않음
