REST API, 알고 사용하자!

 

📘 REST API의 정의

 우선, REST가 어떤 것을 의미하는지 알고 가도록 하자.

 REST는 Representational State Transfer의 약자이며, 다음과 같이 구성되어있다.

• 자원 (Resource) : URI
• 행위 (Verb) : HTTP Method
• 표현 (Representations)

->  따라서 REST API는 URI를 통해서 자원을 나타내고, HTTP Method를 이용해 해당 자원의 행위를 규정하여 그 결과를 받는 것을 의미한다.

 

 

💡REST의 특징

• Uniform Interface
  • URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 스타일을 말한다.
• Stateless
  • REST는 무상태성 성격을 갖고, 작업을 위한 상태정보를 따로 저장하거나 관리하지 않는다. 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다.
  • 이를 통해서 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않는다.
• Cacheable
  • 기존 웹 표준을 그대로 사용하기 때문에 HTTP가 가진 캐싱 기능을 적용할 수 있다.
• Self-descriptiveness
  • REST API 메세지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있다.
• Client-Server 구조
  • REST 서버는 API를 제공하고, 클라이언트는 사용자 인증이나 컨텍스트 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간의 의존성이 줄어들게 된다.
• 계층형 구조
  • REST 서버는 다중 계층으로 구성될 수 있으며, 로드 밸런싱, 암호화 계층 등을 추가해 구조상의 유연성과 프록시, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.

 

🏗️ RESTFUL URI설계 원칙

 RESTFUL한 URI를 설계할때 가장 중요한 두가지 중심 원칙은 다음과 같다.

   1️⃣ URI는 정보의 자원을 표현해야 한다.

   2️⃣ 자원에 대한 행위는 HTTP METHOD로 표현해야 한다.

-> 즉, 여기서 중요한 키워드는 "자원(Resource)", "행위(Verb)-HTTP Method" 임을 확인할 수 있다. 해당 키워드에 대해서 제대로 알고 가도록 하자!

 

📄Resource의 종류

 자원의 종류는 총 네가지가 있다.

 1) 문서(Document)

• 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
• 단수 사용 (/device-management, /user-management)

2) 컬렉션(Collection)

• 서버가 관리하는 리소스 디렉토리로, 서버가 리소스의 URI를 생성하고 관리
• 복수를 사용하라
• POST 기반 등록
• 예) /users, /accounts....

3) 스토어(Store)

• 클라이언트가 관리하는 자원 저장소로, 클라이언트가 리소스의 URI를 알고 관리
• PUT 기반 등록
• 예) 정적 컨텐츠 관리, 원격 파일 관리
• 복수 사용 (/files)

4) 컨트롤 URI 혹은 컨트롤러(Controller)

• 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
• 동사를 직접 사용
• 예) GET, POST만 사용할 수 있는 HTTP FORM의 경우 컨트롤 URI(동사로 된 리소스 경로)를 사용한다. ex) /members/delete, /members/new 등
• 동사 사용 (/checkout, /play 등)
• 즉, 자원이 control 자원인 경우에만 예외적으로 동사 사용을 허용하는 것이다. 

 

📄HTTP Method의 종류

- 행위를 표현하기 위해 주로 사용하는 HTTP method는 위의 다섯개와 같다.

- 여기서 HTTP 메소드를 정확히 이해하기 위해서는 멱등성이라는 키워드의 개념을 알고 가야 한다.

 

💡 멱등성(Idempotence)이란?

멱등성이란 여러번 수행해도 그 결과가 같음을 의미한다. 

서버의 상태는 멱등성이 유지되어야 하는 경우 같은 행위를 여러번 반복하더라도 같은 효과를 가져야 한다.

서버에서 응답이 다를 수는 있지만, 요청이 의도한 효과를 발휘할때 멱등성이 유지됨을 의미한다.

• HTTP 메소드에서의 멱등성 

4.2.2.  Idempotent Methods

   A request method is considered "idempotent" if the intended effect on
   the server of multiple identical requests with that method is the
   same as the effect for a single such request.  Of the request methods
   defined by this specification, PUT, DELETE, and safe request methods
   are idempotent.

• 실제 HTTP 명세 문서에 따르면 멱등성을 갖는 메소드란 행위를 한번 요청했을때와 다량으로 요청했을 때가 같은 효과가 나는 것이라고 한다.      
• Data의 상태를 생각해보자. 
  • 함수의 형태로 표현하면 F(F(x))=F(x) 으로 이해하면 쉽다.
  • 1번 유저를 한번 지우거나, 여러번 지우는 요청을 해도 1번 유저가 없는 상태는 같다.
• 멱등성을 가지는 메소드
  • GET/ HEAD/ OPTIONS : 멱등성도 가지며, 서버에 영향을 주지 않아 SAFE한 요청이기도 하다.
  • PUT/PATCH/DELETE 
    • 리소스의 위치를 정확하게 지정하여 재요청을 했을 경우, 리소스 수정/삭제 등의 동일한 결과를 얻을 수 있다. 
    • 하나의 데이터에 대해서만 수정/삭제등을 일으키고, 더이상 똑같은 요청에 대해서는 다른 데이터의 변경을 일으키지 않는다.
  • POST
    • 만약 POST를 여러번 재요청했다고 생각해보자.
    • POST를 한번 요청하는 것과 다량으로 요청하는 것은 리소스를 계속 새로 생성하는것과 한개만 생성하는 것의 차이점을 가진다. 즉 POST의 재요청시에 서버의 상태는 1번 요청했을 때의 서버의 상태와 다르다.
• 서버의 상태가 유지된다는 개념이 상당히 헷갈릴 수 있다. 필자의 경우에도 "수정을 계속 하면 매번 서버 상태가 다른 거 아냐???" 라고 생각했다. 그러나 이는 매번 다른 수정 요청을 보낼 때의 경우이며, 매번 "동일한" 요청을 했을때, 데이터의 상태가 변경된다면 멱등성이 존재하지 않는다고 생각하면 쉽다.

 

🥊PUT VS PATCH

PATCH와 PUT은 둘 다 데이터의 수정을 위한 method이지만, 어떠한 방식으로 리소스를 수정하는지가 다르다.

• PATCH, which is used to apply partial modifications to a resource
• PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload

즉, PUT 메소드는 데이터가 가진 속성에 대한 요청을 일부분만 보낸 경우에는 전달한 필드 이외의 값이 모두 null 또는 default 값으로 처리되어 버린다.

 

그러나, PATCH를 이용하여 변경할 속성에 관해서만 요청을 보내면, 새롭게 바뀐 부분만 반영되며 나머지는 기존의 데이터가 유지된다.

-> 즉 자원의 일부를 수정할때는 PATCH 메소드를, 전체적인 수정이 필요할 때는 PUT 메소드를 사용하게 된다.

---

-이렇게 REST API 설계시 중요한 두 가지 원칙을 기억하면서 URI 설계시 반드시 알아야할 가이드라인을 살펴보자.

 

1. 소문자를 사용한다.

• 주소에서 대소문자를 구분하므로, 카멜형식이 아닌 소문자를 사용하여 작성한다.

- BAD CASE
<http://restapi.com/users/postComments>

- GOOD CASE
<http://restapi.com/users/post-comments>

 

2. 언더바 대신 하이픈을 사용한다.

• 가급적이면 하이픈도 생략해야 하는 이유는, 주소창에 가려져 사용자가 확인하기 어려울수도 있기 때문이다.

- BAD CASE
<http://restapi.com/users/post_comments>

- GOOD CASE
<http://restapi.com/users/post-comments>

 

3. 마지막에 슬래시를 포함하지 않는다.

• 슬래시는 계층을 구분하는 것으로 마지막에는 사용하지 않는다.

 

4. 행위는 포함하지 않는다.

• 행위는 URL 대신 HTTP Method를 사용하여 전달한다.

- BAD CASE
<http://restapi.com/users/1/delete-post/1>

- GOOD CASE
<http://restapi.com/users/1/posts/1>

 

5. 파일 확장자는 URI에 포함하지 않는다.

• REST API에서는 메세지 바디 내용의 포맷을 나타내기 위한 파일 확장자는 URI 안에 포함하지 않는다.

- BAD CASE 
<http://restapi.com/users/photo.jpg> 

- GOOD CASE 
GET <http://restapi.example.com/users/photo> HTTP/1.1 
Host: restapi.example.com Accept: image/jpg

 

6. 가급적 전달하고자 하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

• 항상 Resource가 어떤 범주에 포함되어있는지 확인해야 한다.
• 컨트롤 자원의 경우에는 동사를 직접 사용해서 이름을 짓는다.
• 만약 가용할 수 있는 HTTP method가 GET,POST로 한정된 경우에는 컨트롤 URI를 사용하기 때문에 delete등의 동사로 URI를 설계하기도 한다.

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play