11. REST API & RESTful API

11번째 CS 블로그 주제는 REST API와 RESTful API에 대해서 다뤄보려고 한다!

 

API에 대한 블로그를 작성했을 때 REST API가 잠깐 등장했었는데, 웹 개발자라면 꼭 알아둬야 할 국밥 개념이라고 한다. (맛있겠다...🍲)

 

이번 주제도 확실히 알고 있는 주제가 아니라 이해하는데 시간이 좀 걸리겠지만...

 

뭐가 어찌 됐든 해내야겠지~?

 

그럼 시작해 보자😉

---

REST API & RESTful API

REST(REpresentational State Transfer)란?

웹의 자원을 HTTP URI로 표현하고, HTTP 메서드를 통해 해당 자원에 대한 행위를 정의하는 아키텍처 스타일

즉 REST란, 어떤 자원에 대해 CRUD(Create, Read, Update, Delete) 연산을 수행하기 위해 URI(Resource)로 Get, Post 등의 방식(Method)을 사용하여 요청을 보내며, 요청을 위한 자원은 특정한 형태(Representation of Resource)로 표현된다.

 

REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에, 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다. 바로 저번 주제에서 다뤘던 클라이언트와 서버의 통신 방식 중 하나가 바로 REST이다.

---

URI vs URL

여기서 잠깐!🤚

REST를 설명하는 중에 URI라는 단어가 나왔는데... 우리가 흔히 아는 URL과 비슷하게 생겨서 뭐가 다른 걸까 싶은 생각에 알아보았다😉

URL은 Uniform Resource Locator로 인터넷상 자원의 위치를 의미한다.
URI는 Uniform Resource Identifier로 인터넷상의 자원을 식별하기 위한 문자열의 구성이다.
즉, URI는 URL을 포함하는 개념이며, URI가 URL보다 포괄적인 범위라고 할 수 있다. 

---

REST의 구성 요소

REST의 개념을 보면 대충 감이 잡힐 텐데, REST의 구성 요소는 크게 자원, 행위, 표현 3가지로 나눌 수 있다.

자원(Resource) = URI

웹에서 접근하고 조작할 수 있는 모든 대상을 의미한다.
URI로 표현되며 "무엇을" 요청하는가를 나타낸다.
URI는 명사형으로 표현하며 RESTful을 만족하기 위해서는 리소스의 이름만 포함해야 한다.
( Ex. 전체 사용자 목록 - '/users' , 특정 사용자 - '/users/1' )

행위(Verb) = Method

클라이언트가 자원에 대해 무슨 작업을 할 것인가를 의미하며, HTTP 메서드로 표현된다.
HTTP 메서드는 동사 역할을 하며, URI는 절대 동사를 포함하지 않는다.
( EX. GET - '조회', POST - '생성', PUT - '수정', PATCH - '부분 수정', DELETE - '삭제')

표현(Representation of Resource)

자원 자체가 아니라 클라이언트와 서버가 주고받는 형태를 의미한다.
클라이언트는 이 표현을 받아 리소스를 이해하며, 주로 JSON, XML 형태로 사용한다.
같은 자원이라도 표현 방식에 따라 다르게 전달될 수 있다.

// Ex. JSON
{ 
  "id": 1,
  "username": "hongbu",
  "email": "hongbu@example.com"
}

---

REST의 제약조건

REST의 구성 요소를 알아보고 왔는데, 이제는 제약조건을 알아보려고 한다. (REST의 축복이 끊이질 않는다🤦‍♂️)

 

해당 제약조건은 뒤에 나올 RESTful API를 이해하기 위해서 필요한 개념이니까 확실하게 알아보자.

 

REST는 크게 6개의 제약조건을 갖고 있는데 하나씩 도장 깨기 해보자.

1. Server-Client (서버-클라이언트 구조)

REST에서는 클라이언트와 서버의 역할을 명확하게 분리한다.
서버는 자원을 보관하고, 이를 처리하는 로직을 담당하며 API를 통해 기능을 제공한다.
반면 클라이언트는 사용자의 인터페이스를 담당하고, 서버로부터 필요한 자원을 요청하는 역할을 한다.
이러한 역할의 분리는 시스템의 독립성과 확장성을 높이고, 각 구성 요소의 개발과 유지보수를 유연하게 만들어준다.

2. Stateless (무상태)

REST는 HTTP 프로토콜의 특성인 Stateless를 그대로 따르기 때문에, 각 요청은 서로 독립적이어야 한다.
서버는 클라이언트의 상태를 저장하지 않으며, 각 요청은 필요한 모든 정보를 스스로 포함해야 한다.
예를 들어 인증 정보나 요청과 관련된 데이터는 매 요청마다 함께 전달되어야 하며, 서버는 이전 요청의 맥락(context)을 기억하지 않는다.
이로 인해 구현이 단순해지고 서버 확장이 용이해지는 장점이 있지만, 클라이언트 입장에서는 다소 반복적인 데이터 전송이 발생할 수 있다.

3. Cacheable (캐시 처리 기능)

웹 표준 HTTP 프로토콜을 그대로 사용하므로 웹에서 사용하는 기존의 인프라를 그대로 활용할 수 있습니다.
REST는 웹 표준인 HTTP 프로토콜을 그대로 활용하기 때문에, HTTP가 제공하는 강력한 캐시 기능 역시 사용할 수 있다.
서버는 응답에 Cache-Control, ETag, Last-Modified 등의 헤더를 포함시켜 클라이언트가 응답을 캐시 할 수 있도록 한다.
이를 통해 반복되는 요청에 대해 빠른 응답을 제공할 수 있고, 서버의 부담도 줄일 수 있다.
대량의 요청이 발생하는 시스템에서는 특히 유용하다.

4. Layered System (계층 구조)

REST 시스템은 하나의 서버로 구성되는 것이 아니라, 여러 개의 계층으로 나누어질 수 있다.
예를 들어 로드 밸런서, 인증 서버, 프록시, 게이트웨이 등의 중간 계층이 존재할 수 있다.
클라이언트는 이러한 중간 계층의 존재를 인식하지 못한 채, 단일 API 서버에 요청을 보내는 것처럼 행동한다.
이러한 계층화는 시스템의 보안성, 확장성, 유지보수성을 높이는 데 기여한다.

5. Uniform Interface (인터페이스 일관성)

REST 아키텍처의 가장 핵심적인 요소로, 자원에 대한 요청 방식이 일관되어야 함을 의미한다.
HTTP 표준에 따라 URI는 자원을 식별하고, HTTP 메서드(GET, POST, PUT, DELETE 등)는 자원에 대한 행위를 표현한다.
요청 메시지와 응답 메시지는 그 자체로 의미를 이해할 수 있는 자기 서술적(Self-descriptive) 구조를 가져야 하며, 경우에 따라 하이퍼미디어(HATEOAS)를 통해 다음 행동을 유도할 수 있도록 한다.
이러한 일관성은 REST API가 다양한 플랫폼과 언어에서 폭넓게 활용될 수 있게 만들어주는 중요한 요소이다.

6. Code on Demand (선택적 제약조건)

이 조건은 서버가 클라이언트에 실행 가능한 코드를 전달할 수 있다는 것을 의미한다.
예를 들어 자바스크립트 코드 같은 스크립트를 클라이언트로 보내 클라이언트 측에서 실행하게 할 수 있다.
다만 이 조건은 선택 사항으로, 대부분의 RESTful 시스템에서는 반드시 구현할 필요는 없다.

---

REST API란?

REST(Representational State Transfer) 아키텍처 스타일을 따르는 웹 기반 API

REST는 웹의 장점을 최대한 활용할 수 있도록 설계된 아키텍처 원칙이며 위에서 말했듯,  클라이언트-서버 구조, 무상태성(Stateless), 캐시 처리 기능, 계층화 시스템, 인터페이스 일관성 등의 제약조건을 포함하는 아키텍처 스타일이다.

 

이러한 REST의 원칙을 기반으로 자원을 정의하고, 자원에 대한 행위를 HTTP 표준 방식으로 표현한 것이 바로 REST API라고 한다.

---

REST API의 특징

REST API의 가장 큰 특징은 요청 자체만으로도 해당 요청이 어떤 자원에 어떤 행위를 하려는지 유추할 수 있다는 점이다.

 

즉, URI와 HTTP 메서드만 보면 요청의 목적이 드러나며, 이는 API의 가독성과 유지보수성을 크게 향상시킨다.

 

사실 이렇게 말로만 보면 뭔 말인지 감이 안 잡힐 수 있다.

 

그. 래. 서 예시를 준비해 보았다😎

GET /users/1 → ID가 1인 사용자 정보 조회
POST /users → 새로운 사용자 생성
DELETE /posts/5 → 게시글 5번 삭제

이처럼 URI는 자원을 명시하고, HTTP 메서드는 자원에 대한 행위를 표현하는 방식으로 설계된다.

---

REST API 설계 가이드

그럼 REST API는 어떻게 설계해야 할까?

 

REST API를 설계할 때 지켜야 할 핵심 원칙은 크게 2개가 있다.

1. URI는 자원을 표현해야 하며, 반드시 명사여야 한다.
2. 자원에 대한 행위는 HTTP Method를 통해 표현해야 하며, 절대로 URI에 동사를 포함하지 않는다.

라고는 하지만. 사실 늘 그렇듯 말로만 설명하면 잘 와닿지 않는다. 예시로 확인해 보자.

// 잘못된 REST API 설계 → URI에 명사만 있는 것이 아닌 동사도 포함되어 있음
/getAllUsers
/getUserById
/createNewUser
/updateUser
/deleteUser

// 올바른 REST API 설계 → 동사는 HTTP 메서드로 표현되어 있고 URI에는 명사로만 표현되어 있음
GET    /users         → 사용자 목록 조회
GET    /users/1       → ID 1 사용자 조회
POST   /users         → 사용자 생성
PUT    /users/1       → 사용자 전체 수정
DELETE /users/1       → 사용자 삭제

예시에서 볼 수 있듯, REST API의 동작은 HTTP 메서드로, 동작의 대상은 URI에 명사로 표현되어 있는 것이 REST API 설계의 핵심이라고 할 수 있다.

---

REST API의 설계규칙

방금 다룬 내용이 REST API의 설계 원칙이었다면...

 

REST API를 설계할 때 지켜야 하는 규칙은 또 따로 있다. (참... 까다롭... 다...)

 

뇌용량이 점점 부족해지는 게 느껴지지만... 앞으로 얼마 안 남았으니 좀 더 힘내보자💪

REST API의 설계규칙
1. URI는 동사가 아닌 명사를 사용한다.
2. 슬래시(/)를 통해 리소스의 계층 관계를 표현한다.
→ Ex.  /users/1/posts → 특정 사용자의 게시글 목록
3. URI 마지막에 슬래시(/)를 붙이지 않는다.
→ Ex.  /users (O), /users/ (X)
4. 단어 구분은 밑줄(_)이 아닌 하이픈(-)을 사용한다.
→ Ex.  /user-profile (O), /user_profile (X)
5. URI는 모두 소문자로 작성한다.
→ Ex.  /users, /posts/comments
6. 파일 확장자는 사용하지 않는다.
→ Ex.  /users.json (X)
7. HTTP 응답 상태 코드를 적절히 사용한다.
→ 주요 HTTP 응답 상태 코드

상태코드	메시지	의미
200	OK	요청 성공
201	Created	리소스 생성 성공
400	Bad Request	잘못된 요청
401	Unauthorized	인증 실패
404	Not Found	리소스를 찾을 수 없음
500	Internal Sever Error	서버 에러

뭔가 상당히 많아 보이면서도 적은 느낌이다.

 

대부분 제약조건에서 다룬 개념이거나 REST의 개념, REST API의 설계 원칙에서 다룬 내용이 규칙화되어 있는 느낌이어서 생각보다 어렵진 않았다. (실제로 사용해 보면... 그건 그때 가서 생각해 보자...)

---

RESTful API란?

지금까지 REST, REST API에 대해 설명하면서 'RESTful API'라는 단어를 몇 번 꺼냈었는데, 이제는 이 친구에 대해서 알아야 할 때가 왔다...

---

RESTful API란, REST 아키텍처 원칙을 철저히 따르는 API로, REST의 설계 규칙을 잘 지켜서 설계된 API를 RESTful 한 API라고 칭한다.

 

즉, REST의 원리를 잘 따르는 시스템을 RESTful이란 용어로 지칭하는 것이다.

 

RESTful 하게 만든 API는 URI만 보더라도 어떤 자원에 어떤 행위를 하려는지 쉽게 파악할 수 있다.

RESTful 한 API 예시

GET /users  → 사용자 목록 조회
GET /users/10  → ID가 10인 사용자 조회
POST /users  → 새로운 사용자 생성
PUT /users/10  → ID가 10인 사용자 전체 정보 수정
PATCH /users/10  → ID가 10인 사용자 일부 정보 수정
DELETE /users/10  → ID가 10인 사용자 삭제

RESTful 하지 않은 API 예시

GET /getUserById?id=10  → URI에 동사가 포함됨
POST /createUser  → 자원이 아닌 행위 중심으로 설계됨
POST /updateUser/10  → 수정은 PUT이나 PATCH로 표현해야 함
GET /deleteUser/10  → 조회 메서드(GET)로 삭제를 시도함

---

만약 RESTful 하지 않다면?

물론, 성능이 우선시 되는 API라면 RESTful 한 API가 아니어도 된다. 다만 REST 아키텍처의 원칙을 지키지 않고 설계하는 API가 많아질 경우, 실제로 다양한 문제점과 비효율이 발생하게 된다.

 

우선, URI에 동사를 포함하면 의미가 중복되고 비표준적인 방식이 되어 가독성이 떨어진다.

 

또한, HTTP 메서드를 올바르게 사용하지 않으면 캐시가 불가능하고 요청의 의도가 불명확해진다.

 

리소스 간 관계를 URI로 표현하지 않으면 구조적인 설계가 어려워지고, 응답 형식이나 상태 코드가 일관되지 않으면 클라이언트가 해석하기 힘들어진다.

 

결국 서버와 클라이언트 간 결합도가 높아지고, 웹의 다양한 인프라 기능들도 제대로 활용할 수 없어 성능과 확장성 면에서 손해를 보게 된다.

 

이처럼 RESTful 하지 않은 API는 단순한 규칙 위반을 넘어서, 실질적인 기술적 손해를 유발할 수 있다.

 

당장 성능이 우선시 되어서 RESTful 한 API를 만드는 것이 후순위로 밀릴 수 있지만, REST 아키텍처의 설계 원칙을 잘 따르고, RESTful 하게 API를 설계하는 것이 장기적인 관점으로 보면 훨씬 유리하다.

---

마무리...

그동안 API 연동하면서 POST, GET 요청 보낸 게 나의 API 지식 전부였는데...

 

생각보다 너무 많은 내용의 API 지식이 기다리고 있었다...🥲

 

API를 직접 설계해서 사용해 본 적은 없었는데, API 설계 원칙과 규칙을 찾아보면서 그동안 내가 요청을 보냈던 주소들이 어떻게 구성되는지도 드디어 알게 되었다.

 

앞으로 더 많은 지식을 쌓기 위해 오늘의 공부는 여. 기. 까. 지. 😉

 

오늘도 얇디얇은 지식의 두께를 늘리기 위해 노력한 나에게 박수를 쳐주며 공부를 마무리해보자👏👏