[HTTP] REST API란?

정리하게된 계기

PUT과 PATCH 차이을 비교하는 블로그를 찾으면서 자연스레 RESTful한 API에 대한 블로그를 읽게됐는데 뭐 당연히 GET, POST 이런거 좀 대충 써주면 RESTful하다 라고 생각했는데 내 자신이 참 부족했던 것같다. 전혀 아니였다. 이제껏 수정 API에도 POST를 섞어 쓰는 등 대부분의 요청을 GET, POST를 통해 처리했고 그리고 또 여러 이유들로 내가 설계했던 API는 100% RESTful하다고 볼 수 없다고 생각이 들었다. 그래서 아직 공부하는 입장이니 다시 처음부터 기초를 닦는다고 생각하고 다시 정리해보기로 했다.

---

REST와 RESTful이란?

그래서 우선 REST란?
World Wide Web(WWW)와 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식으로 Representational State Transfer의 약어로 네트워크 아키텍처 원리의 모음이다.
네트워크 아키텍처 원리란 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반을 말한다.

그래서 위와 같은 REST 원리를 따르는 시스템을 보고 RESTful하다고 하는 것이다.

 

REST라는 단어를 뜯어보기

REST에서 중요한 3가지 단어가 있다. Resource, Representation, State Transfer이다.

• REST에서 자원(Resource)는 네트워크에 존재하는 모든 정보 또는 개체를 의미한다.
  ex) 사용자 정보, 이미지, 텍스트 문서 등 
  고유한 URI(Uniform Resource Identifier)로 식별된다.
• Representational은 위의 자원에 대한 표현을 말한다. 즉, 자원의 표현(Represnetation)은 여러 형태로 표현될 수 있는데 예시로는 가장 대표적으로 JSON 그리고 XML, HTML 등의 형태로 표현된다.
  그래서 클라이언트로 부터 위와 같은 자원의 표현으로 요청을 받아서 이를 처리하고 또 클라이언트로 저러한 표현들로 응답해준다.
• 그리고 마지막으로 상태 전이(State Transfer)은 서버에서 위와 같은 '자원의 표현'의 전송으로 클라이언트는 이 표현을 받아 상태를 전이하는 것이다. 예를 들어보면 내 블로그 게시글의 목록에서 특정 게시글을 클릭하면 그 특정 게시글에 대한 자원(데이터)들이 자원의 표현으로 클라이언트로 넘어가고 그 특정 게시글을 보여주는 화면으로 넘어가는 것을 보고 상태가 전이된다고 한다.

 

REST 아키텍처에 적용되는 6가지 제한 조건

1. 클라이언트-서버 구조(Client-Server Architecture):
   • 자원을 가지고 관리하는 서버와 그 자원을 요청하는 클라이언트로 구성된다.
   • 클라이언트와 서버는 독립적으로 분리되어서 각 파트가 독립적으로 개선될 수 있도록 한다.
   • 클라이언트는 사용자 인터페이스를 관리하고, 서버는 데이터 저장 및 비즈니스 로직을 관리한다.
2. 무상태(Stateless):
   • 서버에서 각 요청은 독립적으로 처리해야 하며, 이전 요청의 상태를 기억하지 않는다.(서로의 상태 저장할 필요가 없다.)
   • 즉, 각 요청 간에 클라이언트의 컨텍스트가 서버에 저장되면 안된다.
   • HTTP 프로토콜 자체가 Stateless한데 REST가 이 HTTP를 사용하기 때문에 REST 역시 Stateless하다.
   • 클라이언트는 모든 필요한 상태 정보를 요청에 포함시켜야 한다.
3. 캐시 가능(Cacheable):
   • 응답은 명시적으로 캐시 가능해야 한다.
   • 클라이언트는 응답을 캐시하고, 동일한 요청에 대해 서버에 재요청하지 않고 캐시된 응답을 사용할 수 있습니다.
4. 계층화(Layered System):
   • 서버가 계층화된 시스템 아키텍처를 사용할 수 있어야 한다.
   • 클라이언트와 서버 사이에 중개 계층(프록시, 게이트웨이 등)을 둬서 보안, 캐시 등의 역할을 해줄 수 있게 한다.
   • 위와 같이 프록시 서버를 둔 경우 WAS에서는 순수 비즈니스 로직만 수행할 수 있고 앞단에서 SSL처리, 로드 밸런싱 등을 처리하도록할 수 있다.
5. 코드 온 디맨드(Code on Demand) - optional:
   • 유일한 선택적 제약 조건
   • 서버는 클라이언트에게 실행 가능한 코드를 전송할 수 있다.
   • 예를 들어, 클라이언트가 서버에 코드를 요청하여 서버는 JavaScript를 클라이언트에 전송하여 스크립트 코드를 실행할 수 있다.
6. 인터페이스 일관성(Uniform Interface):
   • REST는 자원에 대한 일관적이고 한정적인 인터페이스를 제공한다.
   • 그래서 자원에 대한 요청을 통일하고 한정적인 인터페이스로 수행하는 아키텍처 스타일이다.
   • 한정적인 인터페이스에는 GET, PUT, POST, DELETE 4가지가 포함된다.
   • 간단히 말해서 REST는 클라이언트와 서버 간의 상호 작용을 위한 일관되고 통일된 인터페이스를 정의한다. 예를 들어, HTTP 기반 REST API는 표준 HTTP 메서드(GET, POST, PUT, DELETE 등)와 URI(Uniform Resource Identifiers)를 사용하여 리소스를 식별한다.

< 일관된 인터페이스를 위한 4가지 인터페이스 규칙 >

Identification of Resources
: 인터페이스는 클라이언트와 서버 간의 상호 작용에 관련된 각 리소스를 고유하게 식별할 수 있어야 한다.

Manipulation of Resources Through Representations
: 클라이언트가 어떤 자원을 지칭하는 메시지와 특정 메타데이터만 가지고 있다면 이것으로 서버 상의 해당 자원을 변경·삭제할 수 있는 충분한 정보를 가지고 있는 것이다.

Self-Descriptive Messages
: 자신을 어떻게 처리해야하는지 정보를 포함해야한다. 
예를 들어 MIME type과 같은 인터넷 미디어 타입을 전달한다면, 그 메시지에는 어떤 파서를 이용해야 하는지에 대한 정보도 포함해야 한다. 미디어 타입만 가지고도, 클라이언트는 어떻게 그 내용을 처리해야할 지 알 수 있어야 한다. 메시지를 이해하기 위해 그 내용까지 살펴봐야 한다면, 그 메시지는 자기서술적이 아니다. 예를 들어, 단순히 "application/xml"이라는 미디어 타입은, 실제 내용을 다운로드 받지 않으면 그 메시지만 가지고는 무엇을 해야할지에 대해 충분히 알려주지 못한다.

Hypermedia as the Engine of Application State
: 만약에 클라이언트가 관련된 리소스에 접근하기를 원한다면, 리턴되는 지시자에서 구별될 수 있어야 한다. 충분한 콘텍스트 속에서의 URI를 제공해주는 하이퍼텍스트 링크의 예를 들 수 있겠다.

RESTful API Naming 규칙

1. 복수를 더 지향하자. 단수를 사용해도 상관없지만 혼용은 지양해야함.
   GET /users가 여러 유저를 들고오는 것이고 
   POST /users는 유저 Array에 하나의 유저를 추가하는 것이므로 자연스러우며
   GET /users/:id 특정 유저를 조회하는 요청 또한 유저 Array에서 특정 유저를 조회하는 것이므로 자연스럽다.
2. 동사보다 명사를 사용하자
   POST /createUsers 보다는 POST /users
   GET /getUserById/12 보다는 GET /users/12 이렇게 했을때 훨씬 규칙적이고 체계적으로 와닿는다.
3. 대문자보다 소문자
   일반적으로 URI 경로에서 소문자를 사용한다.  사실 URL에서 프로토콜과 호스트 주소는 대소문자를 구분하지 않지만, 리소스 경로 부분은 운영체제 등에 따라 구분하는 경우가 있다. 윈도우 운영체제라면 디렉터리나 파일이름에서 대소문자를 구분하지 않으나, 리눅스 혹은 유닉스 계열의 서버라면 대소문자를 구분한다. 그래서 혹시 몰라서 소문자로 통일하는 것이다.
   
   
4.  밑줄(_)보다는 하이픈(-)
   리소스가 길어지는 경우, 하이픈(-)을 이용해서 구분하는 것이 가독성에 좋다.
   
   
5. 마지막에 슬래쉬(/) 포함X
   
   
6. 파일 확장자는 URI에 포함하지 않음
7. 행위를 포함하면 안된다.
   DELETE /delete-post/1 가 아니라
   DELETE /post/1 이런식으로 한다.

 

RESTful API HTTP Method

아래 5가지 HTTP Method를 상황에 맞게 사용하면 된다.

• GET: 자원을 받아올때(Read)
• POST: 새로운 자원을 추가할때(Create)
• PUT: 존재하는 자원을 변경할때(Update)
• PATCH: 한 자원의 데이터를 부분적으로 변경할때(Update)
• DELETE: 자원을 삭제할 때(DELETE)

이렇게 됐을때 CRUD가 가능하다.

 

참고: https://restfulapi.net/