[Network] HTTP Request Method와 Restful API

HTTP Request Method

  HTTP Request Method는 클라이언트가 웹 서버에게 request를 날릴 때 그 목적 및 종류 등을 표현한다. GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH 이렇게 총 9가지의 종류가 존재한다. 이전에는 GET, POST을 제외한 대부분의 메소드는 실제로 사용되지 않았다. 그러나 Restful API라는 개념이 주목받기 시작하면서 PUT, DELETE, PATCH 등을 포함한 그 외의 메소드들 역시 이전보다 활용도가 높아지게 되었다.

 

 

Restful API

  그렇다면 Restful API가 무엇일까? Restful API는 이름대로 REST 다운 REST API를 말한다. Restful API의 목적은 이해하고 사용하기 쉬운 Rest API를 구현하는 것에 있으며 성능 향상에 목적을 두는 것은 아니다.

  Restful API를 개발하기 위해서는 우선적으로 request의 목적에 가장 적합한 메소드를 선택해야 한다. 예를 들어서 생성, 갱신, 삭제 등을 모두 POST로 처리하는 것은 전혀 Restful하지 않다. 또 다른 예시로 API endpoint에 리소스명, id 외의 정보가 포함되는 것도 Restful하지 못하다.

 

이어서 가장 Restful API에서 많이 사용되는 (최소한 내가 사용해본) request method들을 정리해보겠다. 

 

1. GET (CRUD)

  가장 많이 사용되는 메소드라고 봐도 과언이 아닐 것이다. 간단하게 말해서 서버에서 데이터를 가져오기 위해서 사용한다. request에 body를 첨부시킬 수는 있지만 일반적인 경우에는 URL을 통해 원하는 리소스를 표현하므로 body를 사용하지 않는다.

 

2. POST (CRUD)

  리소스를 생성하기 위해 사용하는 메소드이다. 이전에 GET, POST 두 개의 메소드만을 활용하던 시절에는 데이터를 단순 조회하는 request는 GET을, 그 외에 서버에 무언가 변화를 일으키는 생성, 삭제, 갱신 등 모든 작업들은 POST를 통해서 이루어졌다. 그러나 Restful API에서 POST는 순수하게 생성만을 담당한다. 

 

3. PUT (CRUD)

  리소스를 갱신하기 위해 사용하는 메소드이다. 쉬운 말로 리소스를 아예 갈아엎는다고 생각하면 된다.

 

4. PATCH (CRUD)

  마찬가지로 리소스를 갱신하기 위해 사용된다. 그러나 리소스의 일부만을 수정할 때 사용한다.

 

※ PUT vs PATCH 쉽게 구별하기

  위에서 표현했지만 PUT은 특정 리소스를 아예 갈아엎고 PATCH는 일부분만을 수정할 때 사용된다. 예를 들어서 name과 age를 가지는 Student 데이터가 존재한다고 치자. 만약 name과 age를 모두 수정하고 싶다면 PUT을, name과 age 둘 중 하나만을 수정하고 싶다면 PATCH를 사용하면 된다. 그렇기 때문에 PUT을 사용할 때는 데이터가 가지는 모든 값을 전송해줘야 하는 반면 PATCH는 변경을 원하는 프로퍼티만을 전송해주면 된다. (만약 PUT에서 일부 프로퍼티를 누락하면 null 값이 담기기 때문에 원치 않는 오류가 발생할 수 있다. 아래는 Student 데이터를 활용한 PUT과 PATCH 비교 예시이다. URL의 마지막에 위치한 값은 student id값의 예시이다.

	PUT (성공)	PUT (실패)	PATCH 1	PATCH 2
URL	PUT /student/3	PUT /student/3	PATCH /student/3	PATCH /student/3
request body	{     name : '김철수',     age : 30 }	{     name : '김철수' }	{     name : '김철수', }	{     age : 30, }

  

※ 데이터 생성을 위해 PUT을 사용하기도 한다?

  데이터 갱신과 생신 두 경우 모두에 PUT을 사용하는 경우도 존재한다. 이 경우에는 기존에 생성을 위해 사용하는 POST와 헷갈릴 수 있는데 PUT request는 멱등성을 가지지만 (idempotent) POST는 그렇지 않다는 뜻이다. 간단하게 얘기해서 PUT은 몇 번을 실행해도 결과가 같지만 POST는 실행할 때마다 똑같은 내용의 리소스가 매번 생성되어서 서버에 side effect를 유발할 수 있다.

 

5. DELETE (CRUD)

  이름 그대로 특정 리소스를 제거할 때 사용된다. DELETE request에서 필요한 유일한 정보는 삭제할 리소스의 id이며 이 역시 url을 통해 표현하면 되므로 request body가 사용되지 않는다.

 

 

  아래 이미지는 모든 HTTP request Method에 대한 정보를 간략하게 정리한 것이다.

출처 : https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods

 

Rest API 설계 규칙

  적합한 Request Method를 선택하는 방법을 알아봤으니 Rest API의 설계 규칙을 공부해서 Restful API를 만들어보자. Rest API에는 다음과 설계 규칙들이 존재한다.

 

(1) 슬래시 구분자는 계층 관계 구별을 위해 사용한다.

ex) /product/food

 

(2) URI 마지막에는 슬래시를 사용하지 않는다.

ex) /product/food/ → (X)

 

(3) URI 가독성을 높이기 위해 하이픈(-)을 사용한다. 밑줄(_)은 사용하지 않는다.

 

(4) URI 경로는 소문자로 작성한다. (URI 스키마 및 호스트를 제외하고는 대소문자가 구별되기 때문에 통일성을 준수해야 한다.)

 

(5) 파일 확장자는 URI에 포함시키지 않는다. (파일 확장자는 Accept 헤더를 통해 표현한다.)

ex) /user/3/profile-image.jpg → (X)

ex) /user/3/profile-image (Accept Header : image/*) → (O)

 

(6) 리소스 간 연관관계가 존재하는 경우 /리소스A/리소스A id/리소스A의 리로스 B와 같은 형식을 따른다.

ex) /user/3/comments (id 3번 유저의 댓글들)

 

 

이번 포스트의 내용을 정리해서 만들어본 대표적인 Restful API의 예시는 다음과 같다.

원하는 작업	HTTP Request Method	API URI	API URI 예시
리소스 목록 조회	GET	/resource	/user/3/post
리소스 하나 조회	GET	/resource/:id	/user/3/post/1004
리소스 생성	POST	/resource	/user/3/post
리소스 전체 수정	PUT	/resource/:id	/user/3/post/1004
리소스 일부 수정	PATCH	/resource/:id	/user/3/post/1004
리소스 삭제	DELETE	/resource/:id	/user/3/post/1004

(참고로 위의 API URI 예시는 3번 id를 가진 유저의 게시글들과 관련된 작업을 처리하는 예시이다.)