[모던 자바스크립트 Deep Dive] - (7) REST API

REST API?

개발을 진행하다보면 REST, REST API, RESTful이라는 용어를 한번씩은 만나봤을텐데, 각각 뭘 의미하는 걸까요?

먼저 API(Application Programming Interface) 는 서로 다른 소프트웨어 시스템 간 상호작용을 가능하게 해주는 인터페이스로, 웹에서는 주로 클라이언트와 서버 간의 통신을 위한 규칙을 정의합니다. API를 사용해 클라이언트는 서버에 특정 데이터를 요청할 수 있고, 서버는 요청에 맞는 데이터를 제공하게 됩니다. 예를 들어, 인스타그램 API를 사용하면 클라이언트는 특정 사용자의 게시글을 요청할 수 있고, 서버는 해당 게시글 데이터를 반환하게 됩니다.

REST(Representational State Transfer)는 웹에서 클라이언트와 서버 간의 통신을 HTTP 프로토콜 위에서 효율적으로 수행하기 위한 아키텍처 스타일입니다. REST의 핵심 원칙은 클라이언트와 서버 간 자원(Resource)의 상태를 주고받는 것입니다. 클라이언트는 필요한 자원 상태를 요청하고, 서버는 이를 전달하는 역할을 담당해 각자의 책임과 역할을 명확히 구분합니다.

이러한 REST 원칙을 준수하여 설계된 API를 REST API라고 하며, RESTful이라는 표현은 REST의 원칙을 충실하게 구현한 시스템을 의미합니다. RESTful API는 예측 가능한 URL 구조와 HTTP 메서드를 통해 직관적인 인터페이스를 제공하게 됩니다.

REST API의 구성 요소

REST API는 크게 자원(resource), 행위(verb), 표현(representation) 이라는 세 가지 요소로 구성됩니다. 이 요소들로 인해 HTTP 요청만으로도 명확하게 데이터의 의도와 목적을 이해할 수 있습니다.

자원

자원은 클라이언트와 서버 간에 주고받는 데이터로, URI(Uniform Resource Identifier)로 표현됩니다. 예를 들어, "맥주"에 대한 정보를 다루는 API가 있다고 하면 /beers는 모든 맥주 목록을 나타내는 자원이고, /beers/1 ID가 1인 특정 맥주를 의미합니다.

ex) https://api.example.com/beers/1
여기서 beers는 맥주 목록이라는 자원을 의미하고, 1 특정 맥주의 고유 ID입니다.

행위

행위는 자원에 대해 수행할 작업을 나타내며, HTTP 요청 메서드로 표현됩니다.

• GET: 자원을 조회 (예: GET /beers/1 — ID 1인 맥주 조회)
• POST: 자원을 생성 (예: POST /beers — 새로운 맥주 추가)
• PUT: 자원을 전체 업데이트 (예: PUT /beers/1 — ID 1인 맥주 정보 전체 변경)
• PATCH: 자원의 일부 수정 (예: PATCH /beers/1 — ID 1인 맥주 정보 일부 변경)
• DELETE: 자원을 삭제 (예: DELETE /beers/1 — ID 1인 맥주 삭제)

예를 들어, 특정 맥주 정보를 조회하고 싶다면 GET 메서드를 사용해 GET /beer/1 요청을 보낼 수 있습니다.

표현

표현은 요청이나 응답에서 자원의 상태를 구체적으로 나타내는 데이터입니다. 일반적으로 JSON 형식으로 클라이언트와 서버가 자원 상태를 주고받는 데 사용됩니다. 예를 들어 새로운 맥주를 추가하고 싶을 때, 다음과 같이 POST /beers 요청 본문에 필요한 정보를 담습니다.

예시: POST /beers 요청 시

{
  "name": "guinness",
  "brewery": "Guinness Brewery",
  "alcohol": "4.2%"
}

여기서 name, brewery, alcohol 속성은 클라이언트가 서버에 전달하는 자원 표현입니다.

페이로드: 요청이나 응답의 본문에 담긴 실제 데이터

자원의 표현에 의한 상태 전달

REST API의 핵심 개념 중 하나인 자원의 표현에 의한 상태 전달은 자원을 요청하면서 특정 상태를 전달해 서버가 자원의 상태를 변경하도록 하는 방식입니다.
이것을 맥주로 예시로 들어 클라이언트(손님)가 서버(바텐더)에게 맥주를 주문하는 상황이 있다면,

손님이 POST /beers 요청과 함께 "guinness" 맥주 한 병이라는 표현을 서버에 전달하면, 서버는 주문을 받고 맥주를 준비해 자원을 생성합니다.
같은 맥주를 다시 주문하고 싶다면, GET /beers/guinness 요청을 보내 맥주 자원의 상태(정보)를 조회할 수 있습니다.
만약 손님이 PATCH /beers/guinness 요청과 함께 "guinness 맥주의 온도를 낮추기"라는 표현을 전달한다면, 서버는 해당 자원의 온도를 낮춰줍니다. 여기서 클라이언트가 전달한 정보가 서버의 자원 상태를 변경하게 되는 것입니다.

이처럼, 클라이언트가 자원의 상태(맥주 정보)를 요청이나 업데이트 요청으로 표현해 전달하면 서버는 해당 요청에 맞춰 자원 상태를 업데이트하거나 정보를 제공하여 REST API의 원칙을 실현하게 됩니다.

REST API 설계 기본 원칙

REST API 설계의 핵심 원칙은 크게 두 가지가 있습니다. URI는 자원을 명확하게 표현해야 하며, 행위는 HTTP 요청 메서드로 나타내야 한다는 것입니다. 이러한 원칙은 RESTful API의 일관성과 가독성을 높이는 중요한 원칙입니다.

1. URI는 리소스(정보의 자원)를 표현해야한다.

URI는 자원을 고유하게 식별할 수 있어야 하며, 동사 대신 명사로만 구성됩니다. 자원 경로는 명확하고 직관적이어야 하므로, GET, POST와 같은 메서드명이나 동작에 대한 설명을 포함하지 않습니다.

• 잘못된 예시

  • GET /getTodos/1
  • GET /todos/show/1

• 올바른 예시

  • GET /todos/1
  • DELETE /todos/1

2. 리소스에 대한 행위는 HTTP 요청 메서드(GET, PUT, POST, DELETE 등)로 표현한다.

HTTP 요청 메서드는 클라이언트가 서버에게 요청의 목적을 전달하는 방법입니다. CRUD 기능을 구현하는 경우 다음과 같은 HTTP 메서드로 구현합니다.

HTTP 요청 메서드	종류	목적	페이로드
GET	index/retrieve	모든/특정 리소스 취득	x
POST	create	리소스 생성	o
PUT	replace	리소스의 전체 교체	o
PATCH	modify	리소스의 일부 수정	o
DELETE	delete	모든/특정 리소스 삭제	x

예를 들어, GET /todos/1로 특정 할 일 데이터를 조회하고 DELETE /todos/1로 해당 데이터를 삭제할 수 있습니다. GET과 DELETE 요청에는 데이터 본문이 없으며, POST, PUT, PATCH는 데이터가 포함된 요청 본문(페이로드)을 전달합니다.

• 잘못된 예시
  • GET /todos/delete/
• 올바른 예시
  • DELETE /todos/1

게시판과 같은 페이지를 만들다보면 게시글 작성, 게시글 조회, 게시글 수정, 게시글 삭제 와 같은 기본적인 기능들을 만들게 되는데, CRUD와 메서드로 구분하게 되면 아래와 같습니다

• 게시글 생성 - Create - POST
• 게시글 조회 - Read - GET
• 게시글 수정 - Update - PUT / PATCH
• 게시글 삭제 - Delete - DELETE

여기서 만약 모든 동작을 POST로 처리한다면 RESTful하지 못하게 되므로, 각 동작에 맞는 메서드를 사용해야 합니다.

REST API 설계 규칙

위 두가지 기본적인 원칙외에도 RESTful 설계를 위해 추가적인 규칙들이 있습니다.

1. 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.

http://api.example.com/api/test

2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

http://api.example.com/api/test (O)
http://api.example.com/api/test/ (X)

3. 밑줄(_) 대신 하이픈(-)을 사용하여 가독성을 높인다.

/user-profile (O)
/user_profile (X)

4. URI는 소문자로 구성한다.

URI는 대소문자를 구별하므로, 혼동을 피하기 위해 소문자로만 구성합니다.

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

RESTful URI는 리소스를 표현하는 데 집중하며 파일 형식에 구애받지 않도록 합니다.

6. HTTP 응답 상태 코드 사용

클라이언트는 해당 요청에 대한 실패, 처리완료 또는 잘못된 요청 등에 대한 피드백을 받기 위해 적절한 HTTP 응답 상태 코드 사용

RESTful API의 장점

RESTful API를 올바르게 설계하면 다음과 같은 장점이 있습니다.

1. 확장성: REST API는 서버가 상태를 저장하지 않는 무상태(stateless) 아키텍처이므로 각 요청이 독립적으로 처리됩니다. 이는 서버의 부하를 줄이고, 캐싱을 통해 반복 요청을 줄여주는 구조 덕분에 트래픽이 증가해도 시스템 확장이 용이해집니다.

2. 유연성: 클라이언트와 서버는 서로 독립적으로 개발되고 확장될 수 있습니다. 클라이언트가 기존 로직을 수정할 필요 없이 서버의 기능을 확장하거나, 서버의 변경을 클라이언트와 분리하여 유연한 업데이트와 확장이 가능합니다.

3. 독립성: REST API는 특정 프로그래밍 언어나 플랫폼에 의존하지 않고 다양한 환경에서 구현될 수 있습니다. 이는 클라이언트와 서버 간의 기술 스택이 다르더라도 동일한 API를 사용할 수 있게 하여, 통신 방식에 영향을 주지 않고도 시스템 간 상호작용을 가능하게 합니다.

⭐️ 마무리

요즘 채용 공고에서 RESTful API 기반 프론트엔드 개발 경험을 자격 요건이나 우대 사항으로 많이 보게 되는데, RESTful은 GET이나 POST와 같이 실제로 자주 사용하는 익숙한 메서드와 밀접한 관계가 있으므로 이번 기회에 제대로 이해해 둬야겠습니다!!

---

출처:
모던 자바스크립트 Deep Dive 44장 REST API (830p ~ 841p)
AWS - RESTful API란 무엇인가요?

---