✴️ HTTP API를 만들어보자
다음과 같은 요구사항이 주어졌다.
회원 정보 관리 API를 만들어라.
이것은 과연 좋은 URI 설계일까?
가장 중요한 것은 리소스 식별이다!
위와 같은 조언을 통해 새롭게 URI를 설계해보자.
새로운 API URI 설계
- 회원 목록 조회:
/members - 회원 조회:
/members/{id} - 회원 등록:
/members/{id} - 회원 수정:
/members/{id} - 회원 삭제:
/members/{id}
여기서 member가 아닌 members라고 한 이유는 계층 구조 상 상위를 컬렉션으로 보고 복수 단어 사용을 권장하기 때문이다. 또한 URI는 리소스를 판별하는 데 사용해야 하므로 "회원"이라는 키워드에 맞춰 URI를 설계한 것이다.
그렇다면 회원 조회/등록/수정/삭제는 어떻게 구분할 수 있을까?
조회/등록/수정/삭제와 같은 행위는 HTTP 메서드를 통해 구분할 수 있다❗️
✴️ HTTP 메서드 - GET, POST
먼저 HTTP 메서드는 클라이언트가 서버에 무언가를 요청할 때 기대하는 행동이다.
HTTP 메서드는 총 9가지 정도로 구성되어 있으나, 위에서 언급한 다섯 가지가 대표적이다.
이 중에서 PUT과 PATCH를 구분하는 데 있어 조금 혼동이 있을 수도 있는데, PUT은 데이터를 전달했을 때 중복되는 데이터가 없다면 새로 생성하고, 있다면 덮어쓰는 행동을 말한다. PATCH는 데이터 내 일부를 변경하는 행동을 말한다.
더불어 최근에는 이 리소스라는 단어가 Representation(표현) 으로 변경되기도 했다.
이외에도 위와 같은 메서드들이 존재하나, 잘 사용하지는 않으므로 존재 정도만 알아두면 될 것 같다.
⚡️ GET
- 리소스 조회 용도
- GET 요청 메세지의 형태
GET - path - HTTP/version
HOST
본래 GET 요청 메세지에서는 메세지 바디를 포함하지 않는데, 최근 스펙에는 메세지 바디를 포함해서 데이터를 전달할 수 있도록 허용하고 있다.
하지만 보통 GET 요청에서는 path에 쿼리 파라미터와 쿼리 스트링을 통해 데이터를 포함시켜 전달하는 경우가 대부분이기 때문에, 메세지 바디를 잘 사용하지는 않는다. 왜냐하면 최근 스펙에서 허용하기는 하지만, 이것을 지원하지 않는 서버들이 많기 때문❗️
위와 같은 예시를 살펴보자.
클라이언트로부터 GET 요청 메세지를 받은 서버는 /members/100 에 해당하는 json 형태의 데이터를 찾게 된다.
찾은 데이터에 대해 클라이언트에게 응답 메세지를 보낼 때, 응답 메세지의 형태는 다음과 같다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 34
[공백 라인]
{
"username": "young",
"age": 20,
}
⚡️ POST
- 클라이언트가 요청한 데이터의 처리 용도.
- POST 요청 메세지의 형태
POST - path - HTTP/version
Content-Type
Space
Message Body
클라이언트가 메세지 바디에 데이터를 포함시켜서 POST 요청 메세지를 서버로 전달하면, 서버는 메세지 바디를 통해 들어온 데이터를 처리하는 모든 기능을 수행한다.
주로 전달된 데이터로 신규 리소스를 등록하고, 프로세스를 처리할 때 POST를 사용한다.
예시를 살펴보자.
클라이언트가 다음과 같이 POST 요청 메세지를 서버에게 보낸다. 이때 클라이언트와 서버는 이 요청에 대해 어떤 동작을 수행할 것인지(ex> 회원 등록) 미리 정해놓는다.
클라이언트의 메세지를 받은 서버는 클라이언트와 약속한대로 데이터베이스에 회원을 등록하고, 신규 리소스 식별자를 생성한다.
그리고 클라이언트에게 다음과 같은 응답 메세지를 전송한다. 지금 예시는 회원이 생성된 상태이기 때문에 201 Created와 같은 메세지가 포함되어있으며, 기존 path + 생성된 리소스 식별자를 Location으로 전달한다. 마지막으로 메세지 바디에는 등록한 데이터를 넣는다.
🤔 POST는 요청 데이터를 어떻게 처리한다는 뜻일까?
POST 메서드는 대상 리소스가 리소스의 고유한 의미 체계에 따라 요청에 포함된 표현을 처리하도록 요청한다.
- Ex1> HTML 양식에 입력된 필드와 같은 데이터 블록을 데이터 처리 프로세스에 제공.
- Ex2> 게시판, 뉴스 그룹, 메일링 리스트, 블로그 등에 메세지를 게시.
- Ex3> 서버가 아직 식별하지 않은 새 리소스를 생성.
- Ex4> 기존 자원에 데이터를 추가.
➡️ 이 리소스 URI에 POST 요청이 오면 요청 데이터를 어떻게 처리할지를 리소스마다 따로 정해야 한다❗️ 정해진 것이 없기 때문이다.
1. POST는 주로 새로운 리소스를 생성/등록하기 위해 사용한다.
2. 프로세스를 처리하는 데에도 POST를 사용한다.
- POST를 통해 새로운 리소스가 생성되지 않을 수도 있다.
- 그렇다 할지라도, 서버에서 큰 변화가 일어나는 것은 POST를 사용해야 한다.
- URI 설계 시 최대한 리소스만으로 설계하되, 어쩔 수 없는 부분들은 컨트롤 URI로 설계해야 한다. (행위 포함)
3. 다른 메서드로 처리하기 애매한 경우
- JSON 형태로 데이터를 넘기려고 하는데 GET 메서드는 메세지 바디를 사용하지 않으므로 GET 메서드를 사용할 수 없을 때.
- 조회에 대해서는 최대한 GET을 사용하되, 어쩔 수 없거나 애매할 때는 POST를 사용한다.
Reference
