HTTP - HTTP 메서드

HTTP API 설계

이번에는 HTTP API를 설계하는 과정을 배워보자.

당신에게 회원기능에 대한 API를 설계하라는 요청이 들어왔다.

회원 기능은 회원가입, 회원조회, 회원정보 수정, 회원 탈퇴의 4가지 기능이 있다고 가정한다.

그럼 가장 먼저 URI를 설계하게 될 것이다.

우리는 일반적인 명명규칙에 따라

• 회원가입 : /join-member/
• 회원조회 : /read-member/
• 회원정보 수정 : /update-member/
• 회원탈퇴 : /delete-member/

라고 URI를 작성하였다.

 

얼핏 보면 굉장히 잘 설계된 URI처럼 보이지만 실은 그렇지 않다.

URI에서 가장 중요한 것은 리소스를 식별하는 것이기 때문이다.

그렇다면 우리 요구사항에서 리소스는 뭘까?

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

가입, 조회, 정보수정, 탈퇴는 회원이라는 리소스가 행하는 액션이지 실제로 식별해야 하는 것은 member라는 회원 리소스를 식별하여야 한다.

따라서 리소스 식별을 위해서는 회원을 등록,수정,조회하는 것을 모두 배제하고 회원이라는 리소스만 URI에 매핑하는 것이 좋다.

올바른 URI는 다음과 같이 될 것이다.

• 회원 조회 : /members/{id}
• 회원 등록 : /members/{id}
• 회원정보 수정 : /members/{id}
• 회원탈퇴 : /members/{id}

(참고로, 계층 구조상 상위를 컬렉션으로 보고 복수단어를 사용하는 것을 권장하기 때문에 member가 아닌 members를 사용하는 것이 좋다)

 

그런데 이렇게 리소스만 식별하였더니 URI를 구분할 수 없는 문제가 생긴다.

그럼 어떻게 이것을 구분할 수 있을까?

리소스와 해당 리소스를 대상으로 하는 행위를 분리하면 된다.

우리의 리소스는 앞서 설명했듯 회원이라는 개념이다.

그렇다면 행위는 조회,등록,삭제,변경과 같은 리소스가 행하는 액션이 될 것이다.

그럼 URI에서 행위는 어떻게 구분 될까?

여기서 사용되는 것이 바로 HTTP 메서드이다.

---

HTTP 메서드 - GET, POST

HTTP 메서드는 클라이언트가 서버에 요청을 할 때 기대하는 행동이다.

주로 사용되는 HTTP 메서드는 다음과 같다.

• GET : 리소스 조회
• POST : 요청 데이터 처리, 주로 등록에 사용
• PUT : 리소스를 대체, 해당 리소스가 없으면 생성
• PATCH : 리소스 부분 변경
• DELETE : 리소스 삭제

이 중에서도 가장 많이 사용되는 것은 GET과 POST이다.

그외에도 다음과 같은 메서드들이 있다.

• HEAD : GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
• OPTIONS : 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
• CONNECT : 대상 자원으로 식별되는 서버에 대한 터널을 설정
• TRACE : 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행

그럼 GET부터 자세하게 알아보자.

1. GET

GET은 리소스를 조회하는 행위를 의미한다.

서버에 전달하고 싶은 데이터는 query(쿼리 파라미터, 쿼리 스트링)을 통해서 전달한다.

메시지 바디를 사용해서 데이터를 전달 할수는 있지만, 지원하지 않는 곳이 많아서 권장하지 않는다.

 

그럼 GET은 어떻게 진행되는가

우리가 앞서 만들었던 회원조회 기능을 수행한다고 생각해보자.

클라이언트는 GET 메서드를 통해 정해진 URI로 요청 메시지를 보낼것이다.

GET /members/100 HTTP/1.1
Host: localhost:8000

메시지를 보면 쿼리 스트링으로 100이라는 ID 값이 들어간 것을 확인 할 수 있을 것이다.

그러면 서버에는 해당 메시지를 받아 처리하고 응답 메시지를 만들어 데이터를 담아 반환한다.

GET은 보통 조회하는 곳에 많이 사용되기 때문에 로직 자체가 복잡하지 않고 간단한 것이 특징이다.

2. POST 

POST는 요청 데이터를 처리하는 행위를 의미한다.

메시지 바디를 통해 서버로 요청 데이터를 전달하며 서버는 요청 데이터를 처리한다.

일반적으로 메시지 바디를 통해 들어온 데이터를 처리하는 모든 기능을 다 수행하며 주로 신규데이터 등록, 프로세스 처리 등에 사용된다.

 

POST의 진행방식 역시 GET과 비슷하지만 약간의 차이가 있다.

우선 클라이언트가 요청 메시지를 만들어 서버로 보낼 것이다.

POST /members HTTP/1.1
Content-Type: application/json

{
	"userId":"1",
    "username":"hong"
}

요청 메시지를 보면 이전 GET의 메시지와 다르게 파라미터가 존재하지 않는다.

대신 Content-Type을 통하여 바디의 타입을 정하고 메시지 바디의 해당 타입의 데이터를 올려 서버로 보내게 된다.

 

서버가 요청 메시지를 받게 되면 약속되어던 데이터 처리 작업을 진행한다.

이 작업은 수정이 될 수도 있고, 등록이 될수도 있으며 미리 클라이언트와 규약만 되어있다면 어떤 형태든 가능하다.

우리는 POST로 보낼때 신규 회원을 등록한다고 가정해보자.

그렇다면 서버는 신규회원을 등록하고 응답 메시지를 클라이언트로 보낼것이다.

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 34
Location: /members/1

{
	"userId":"1",
    "username":"hong"
}

일반적으로 생성작업의 경우 201 created 코드로 많이 보내게 된다.

또한 Location을 통해 해당 리소스가 생성된 경로를 보내며 바디에는 등록된 리소스에 대한 데이터를 확인 할 수 있다.

 

사실 POST는 대상 리소스가 리소스의 고유한 의미체계에 따라 요청에 포함 된 표현을 처리하도록 요청하는 메서드이다.

예를 들어,

• HTML 양식에 입력 된 필드와 같은 데이터 블록을 데이터 처리 프로세스에 제공
• 게시판, 뉴스그룹, 메일링 리스트, 블로그 또는 유사한 기사 그룹에 메시지 게시
• 서버가 아직 식별하지 않은 새 리소스 생성
• 기존 자원에 데이터 추가

즉, 리소스 URI에 POST 요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야한다.

(바꿔말해 정해진 것이 없다!)

 

조금더 정리해보면 POST는 일반적으로 크게 3가지 경우에 많이 사용된다.

• 새 리소스 생성(등록)

서버가 아직 식별하지 않은 새로운 리소스를 생성하는 경우

• 요청 데이터 처리

단순히 데이터를 생성하거나, 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우

(예를 들어, 주문에서 결제완료 > 배달 시작 > 배달 완료처럼 단순히 값을 넘어 프로세스의 상태가 변경되는 경우)

즉, POST의 결과로 새로운 리소스가 꼭 생성되어야 하는 것은 아니다.

이런 경우에는 URI에 행위를 넣기도 한다.

예를 들어 회원이 달리는 상태와 멈춰있는 상태가 있다고 한다면

POST /members/{memberId}/start-dash

와 같이 URI에 액션이 들어갈 수 있으며 이를 컨트롤 URI라고 부른다.

• 다른 메서드로 처리하기 애매한 경우

예를 들어 JSON으로 조회 데이터를 넘겨야 하는데, GET 메서드를 사용하기 어려운 경우가 이 경우에 속한다.

사실 조금 애매하면 POST로 다 넘겨도 무방하다.