HTTP API 설계
API URI 설계에서 중요한 것은 리소스 식별과 URI 계층 구조를 활용하는 것이다. 회원을 CRUD하는 예시를 들어보자.
- 회원 조회 /read-member-by-id
- 회원 등록 /create-member
- 회원 수정 /update-member
- 회원 삭제 /delete-member
이런 방식으로 URI를 작성하게 되면 리소스를 식별하는 것이 아닌 행위를 분리하는 것이 된다. 다음 URI를 보자.
- 회원 조회 : /members/{id}
- 회원 등록 : /members/{id}
- 회원 수정 : /members/{id}
- 회원 삭제 : /members/{id}
위와 같이 작성하면 회원이라는 리소스만을 식별하는 바람직한 URI가 된다. URI에서 각각의 CRUD 행위는 HTTP method를 통해 구분할 수 있다.
HTTP method
GET
리소스를 조회할 때 사용하며 서버에 전달하고 싶은 데이터는 query를 통해서 전달한다.
최근에는 메시지 바디를 사용해 데이터를 전달할 수 있지만 지원하지 않는 서버가 있기 때문에 권장하지 않는다.
POST
POST는 메시지 바디를 통해 서버로 요청 데이터 전달하는데 이 데이터를 가지고 생성만 하는 것이 아니다. POST의 스펙은 다음과 같다.
대상 리소스가 리소스의 고유 한 의미 체계에 따라 요청에 포함 된 표현을 처리하도록 요청합니다.
이 말은 즉, POST는 데이터를 어떻게 처리할 것인가에 대해 정해진 것이 없기 때문에 대상 리소스 URI에 POST 요청이 오면 처리할 프로세스를 리소스마다 따로 정해야 한다는 것이다.
이러한 특성에 의해 POST는 다음의 상황에서 쓰일 수 있다.
-
새 리소스 생성
: 서버가 아직 식별하지 않은 새 리소스 생성 -
요청 데이터 처리
: 단순히 데이터를 생성하거나 변경하는 것을 넘어 프로세스를 처리해야 할 때 사용하며, POST의 결과로 새로운 리소스가 생성되지 않을 수 있다.ex) POST /orders/{orderId}/start-delivery
'주문 → 결제 완료 → 배달 시작 → 배달 완료' 처럼 프로세스 상태를 변화할 때 -
다른 메서드로 처리하기 애매한 경우
: JSON으로 조회 데이터를 넘겨야 하는데 GET 메서드로는 어려운 경우와 같이 애매하면 POST사용~!
PUT
리소스가 있으면 대체하는 것으로 리소스가 없으면 생성을 한다. 파일 덮어쓰기를 생각하면 이해가 쉽다. POST와의 차이점은 클라이언트가 리소스의 위치를 정확하게 알고 URI를 지정한다는 것이다.
PATCH
리소스를 부분 변경할 때 사용한다. 위와 같은 경우 username은 그대로이고 age만 50으로 수정된다.
DELETE
리소스를 제거할 때 사용한다.
기타 메서드
-
HEAD: GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
-
OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
-
CONNECT: 대상 리소스로 식별되는 서버에 대한 터널을 설정
-
TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행
HTTP method의 속성
안전 Safe
호출해도 리소스를 변경하지 않는 경우에 안전하다고 한다. (GET, HEAD 등)
멱등 Idempotent
f(f(x)) = f(x)
몇 번을 호출하더라도 결과가 같다. GET, PUT, DELETE는 100번을 호출하더라도 결과가 같으므로 멱등하다고 할 수 있다.
멱등이라는 속성은 자동 복구 메커니즘에서 활용할 수 있다. 서버가 TIMEOUT 등으로 정상 응답을 못주었을 때, 클라이언트가 같은 요청을 다시 해도 되는가?
캐시 가능 Cacheable
응답 결과 리소스를 캐시해서 사용해도 되는지의 여부이다. GET, HEAD, POST, PATCH가 캐시가능하지만 POST, PATCH는 본문 내용까지 캐시 키로 고려하여 구현하기 어려워 실제로는 GET, HEAD 정도만 캐시로 사용된다.
참고 자료
