[REST API] 1. REST API란

REST API 란❓

REST 아키텍처 스타일을 잘 지킨 API를 REST API, RESTful API라고 한다.

웹에서 클라이언트와 서버가 서로 통신할 때 어떤 규칙을 사용해서 통신할 것인가?

이 때 여러가지 규칙/방법이 존재하는데

REST 아키텍처 스타일은 그 여러 규칙/방법 중 하나이다.

2000년 로이 필딩이 발표했다.

서비스 인터페이스를 RESTful API이라 지칭하기 전에, REST아키텍처 스타일을 잘 지키고 있는지 체크해야 한다.

 

---

REST 아키텍처 스타일 지침

REST API는 두 컴퓨터(서버와 클라이언트)가 인터넷상에서 소통하기 위해 사용하는

커뮤니케이션 표준 중 현재 가장 널리 사용되고 있다.

REST아키텍처 규칙은 아래 6가지가 있다.

1. Uniform Interface
2. Client-Server
3. Stateless
4. Cacheable
5. Layered System
6. Code on Demand (Optional)

---

1. Uniform Interface : 통일된 인터페이스

우리는 API에 요청을 보낼 때 "엔드포인트"라는 URI을 통해 API에 요청을 보낸다.

통일된 인터페이스란,

URI만을 보고도, 이 API가 어떤 자원에 대한 요청인지 식별 가능해야 한다는 규칙이다.

예를 들어 :

www.example.com/user 이런 엔드포인트가 있을 때,

우리는 이 API가 user, 즉 사용자에 대한 자원을 요청한다는 것을 알 수 있다.

이처럼 URI에 어떤 자원인지를 "명사"형태로 명시하여

API URI가 인터페이스 역할을 하도록 해야 한다는 것이다.

 

또한 URI는 해당 자원에 대해

정보를 요청하는지

정보를 생성하는지

정보를 삭제하는지.. 

등에 대한 "행위"를 묘사하지 않는다.

이러한 행위는 get, post, delete 등의 http 메서드를 통해 정한다.

URI를 자원이라고 보고, 메서드를 동사라고 보는 개발 방식이다.

http메서드 알아보기 링크

 

✅ REST API 인터페이스의 옳은 예

www.example.com/users
www.example.com/product
www.example.com/posts?category=tech

🤮 REST API 인터페이스의 잘못 된 예

www.example.com/getAllUsers
www.example.com/createUser
www.example.com/deleteUser?id=123

 

통일된 인터페이스를 위한 지침내역 한가지가 더 있다.

서버측에서는 API응답 헤더에 Content-Type을 정확히 명시해야 할 것.

클라이언트(브라우저, 기기 등)가 해당 자원을 받았을 때,

어떻게 그 자원을 사용해야 하는지 알 수 있도록 해야한다.

예를 들어 :

API요청에 대한 응답을 받은 클라이언트는

응답 헤더의  Content-Type : image/jpeg 를 보고

"응답으로 온 데이터가 이미지니까 이미지로 렌더링 해야겠다" 라고 처리할 수 있다.

---

2. Client-Server

클라이언트와 서버는 반드시 분리되어야 한다는 원칙이다.

즉, 클라이언트는 UI/UX, 서버는 데이터와 비즈니스 로직만 책임져야 한다는 것이다.

 

✅ 이 원칙이 잘 지켜진 경우 (분리됨):

• 클라이언트: React 웹앱, 모바일 앱 등 → API 요청만 보냄
• 서버: Node.js/Express, Spring 등 → JSON 등으로 응답

 

❌ 분리되지 않은 경우 예시:

1. 전통적인 서버 렌더링

• JSP, PHP, ASP 같은 서버 템플릿이 HTML을 직접 렌더링해서 클라이언트에 전달
• 서버가 UI와 데이터 모두 담당함

2. 서버 내부에 클라이언트 코드가 있는 경우

• 같은 프로젝트 안에 HTML, JS, CSS, 라우팅까지 전부 있음
• 예: Node.js 서버에서 EJS로 뷰까지 처리

---

3. Stateless : 무상태

서버가 사용자의 세션이 유지되고 있는지 여부,

애플리케이션의 상태 등을 저장/기억하지 않는 것을 의미한다.

이런 상태를 서버가 저장하기 시작하면 매 API요청마다 서버가 처리해야 할 일이 복잡해진다.

사용자의 상태, 애플리케이션의 상태 등 서버가 요청을 이해하는데 필요한 정보는

클라이언트 측에서 요청에 포함하여 보내야 한다.

이렇게 함으로써 서버는 매번 요청을 완전히 이해하고 독립적으로 수행할 수 있다.

---

4. Cacheable : 캐시 가능

캐싱은 이전과 같은 요청이 왔을 때

이전에 저장해 놓은(캐싱된) 데이터를 응답함으로써 처리 속도를 향상시키는 기술이다.

REST API는 캐싱이 가능하다.

GraphQL같은 API 구조는 캐싱이 불가능하다.

모든 요청이 Post로만 가고 URI는 항상 동일하기 때문이다.

브라우저가 데이터를 캐싱할 때 참조하는 값은 기본적으로 메소드, URI이기 때문에

GraphQL처럼 모든 요청의 메서드와 URI가 동일하다면 캐싱이 불가능하다.

REST는 자원을 어떻게 사용할 것인지에 대해 메소드로 구분을 주고, 

자원이 다른 경우, URI에 변화가 있기 때문에 데이터를 캐싱할 수 있다.

---

5. Layered System : 계층화된 시스템

계층화된 시스템 아키텍처에서는 

클라이언트와 서버 사이에 여러 중개자(프록시 서버)들이 있어도 된다는 지침이다.

즉, 클라이언트 -> 서버 이렇게 직통이어야만 할 필요는 없다는 뜻.

---

6. Code on Demand (Optional)

서버는 보통 XML이나 JSON으로 응답하지만,

필요하다면 코드 자체를 클라이언트로 보내서,

클라이언트는 단지 응답을 실행시키기만 하면 되도록 만들 수도 있다.

하지만 이젠 JS기반 웹 앱(SPA 등)이 REST API를 사용하는 것이 일반적인데,

이러한 SPA가 동작하는 방식은 html을 먼저 로드하고 

그 뒤 스크립트가 로드 되어 앱이 하이드레이션 되는 방식이다.

이런 방식 또한 Code on Demand의 예라고 할 수 있다.

---

주의 사항

• 클라이언트는, 만약 요청이 500번대 에러로 인해 실패했을 때, 재시도를 할 수 있도록 해야 한다.
• 이 때 주의해야 할 사항은, 재시도를 할 요청이 멱등성이 있는지 없는지를 판단하고 재시도를 해야한다.
• API 엔드포인트가 엄청난 양의 데이터를 반환하는 경우, 페이지네이션을 사용할 것.
• 일반적인 페이지네이션 체계는 limit 및 offset을 매개변수로 사용한다.
  • products?limit=25&offset=50
  • 파라미터가 지정되지 않은 경우 서버는 기본값을 정해두어야 한다.
• API의 버전 관리는 매우 중요하다. 버전 관리는 이전 버전과의 호환성을 제공하는 구현을 하므로 한 버전에서 다른 버전으로 주요 변경 사항을 도입하는 경우 소비자가 다음 버전으로 이동할 수 있는 충분한 시간을 가질 수 있게 된다.
• API를 버전화하는 가장 간단한 방법은 URI의 리소스 앞으로 버전을 접두사로 붙이는 것.
  • /v1/products
  • /v2/products

 

---

참조

• https://aws.amazon.com/ko/what-is/restful-api/
• https://restfulapi.net/
• https://aws.amazon.com/ko/what-is/restful-api/)