REST API & RESTful API

주제 선정 이유

API를 설계하고 호출하며 프로젝트를 진행하다 보면 단순히 URL을 만들고 데이터를 주고받는 것을 넘어
내가 만드는 API가 진정한 의미의 REST 형식을 따르고 있는가 라는 고민이 자연스럽게 들게 되며, 현대 백엔드
개발에서 REST는 기본적인 개념으로 받아들여지지만 정작 REST와 RESTful의 차이가 무엇인지에 대해서는 명확하게 설명하기 어려운 경우가 많고, 단순히 HTTP메서드를 사용하고 JSON, xml을 반환하는 수준에서 머무릅니다.

또한 API를 설계하면서 편의성과 관습에 따라 구현하는 경우가 많아지지만, 그 과정에서 REST가 제시하는 제약 조건과 설계 원칙을 충분히 고려하지 못하고 있다는 생각이 들게 되며, 이러한 부분을 제대로 이해하지 못한다면 일관성 있고
확장 가능한 API를 설계하기 어렵다는 점을 체감하게 됩니다.

그래서 이번 글에서는 REST의 개념과 RESTful의 의미를 다시 정리해보면서, 단순한 구현 방식을 넘어 REST가 가지는 본질적인 설계 원칙과 제약 조건을 이해하고, 이를 기반으로 더 직관적이고 유지보수가 용이한 API를 설계할 수 있는
방향에 대해 정리해보고자 합니다.

REST API가 뭘까?

REST (REpresentational State Transfer)은 자원을 이름으로 구분해 해당 자원의 상태를 주고 받는 모든것을 의미하는데 이걸 정리하면 자원의 표현에 의한 상태 전달을 뜻합니다.

개념	설명
자원 (Resource)	소프트웨어가 관리하는 모든 대상
표현 (Representation)	자원을 표현하는 방식 (예: JSON, XML)
상태 전달 (State Transfer)	요청 시점의 자원 상태를 클라이언트에 전달

REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에, 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이며 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나입니다.

3가지 구성 요소

앞서 언급한 자원, 표현, 상태 전달을 구체화 하기 위해서 세가지 구성요소를 가지게 됩니다.

• 자원
  • URI 모든 자원에는 고유한 ID가 있으며, 이 자원은 Server에 존재하고 클라이언트는 각 자원을 구별하기
    위해 고유한 이름인 URI(Uniform Resource Identifier)를 사용하여 자원을 식별합니다.
• 표현
  • 자원을 어떻게 조작할 것인지에 대한 이름인데 HTTP 프로토콜의 Method(GET, POST, PUT, DELETE)를
    사용해서, 해당 자원에 대해 조회하라, 생성하라와 같은 행위를 명확하게 표현합니다.
• 상태 전달
  • 요청이나 응답 시점에 실제 자원의 데이터가 전달되는 방식인데 현대 API에서는 주로 JSON 형식을 사용하여 클라이언트와 서버 간에 자원의 구체적인 상태를 주고받습니다.

URI는 통합 자원 식별자를 의미하는데 이는 인터넷에 있는 자원(텍스트, 이미지, 동영상 등)을 식별하기 위한 가장
포괄적인 이름이며 URL은 통합 자원 서비스 위치를 의미하는데 흔히 우리가 브라우저 주소창에 입력하는 웹 주소가 바로 URL입니다.

6가지 제약 조건

단순히 HTTP 메서드를 쓴다고 REST가 되는 것이 아니고 로이 필딩이라는 사람이 제시한 아래의 6가지 원칙을 지켜야 비로소 REST API라고 할 수 있습니다.

Client-Server

자원을 가진 서버와 요청을 하는 클라이언트의 역할을 명확히 구분하여 서로 독립적으로 발전할 수 있어야 합니다.

Stateless

서버는 클라이언트의 상태를 저장하지 않고 각 요청은 그 자체로 필요한 모든 정보를 담고 있어야 합니다.

Cacheable

HTTP의 캐싱 기능을 활용해서 대량의 요청을 효율적으로 처리하고 응답 속도를 높여야 합니다.

Layered System

클라이언트는 서버의 복잡한 내부 구조(로드밸런싱, 암호화 등)을 몰라도 되며, 중간 매개체를 통해 다중 계층으로 구성될 수 있어야 합니다.

Uniform Interface

URI로 지정한 자원에 대한 조작이 통일되고 한정적인 인터페이스로 수행되어야 합니다.

• Self-descriptive
  • 메시지만 보고도 그 내용을 완벽히 이해할 수 있어야 합니다.
• HATEOAS
  • 애플리케이션의 상태가 Hyperlink를 통해 전이되어야 합니다.

Code on Demand

서버에서 스크립트 코드를 클라이언트로 내려주어 실행할 수 있게 해야 합니다.

제약 조건을 통한 API 디자인 가이드

로이 필딩이 제시한 제약 조건들은 단순한 이론을 넘어, 실제 API를 설계할 때 우리가 따라야 할 구체적인 가이드라인이 되며 특히 REST의 핵심인 인터페이스 일관성(Uniform Interface)을 지키기 위해, 자원(URI)과 행위(Method)를
어떻게 정의해야 하는지 디자인 규칙을 살펴보겠습니다.

리소스 중심의 URI 설계

가장 중요한 대원칙은 URI는 자원을 표현해야 하며, 행위는 HTTP Method로 나타내야 한다는 것입니다.

원칙	설명	예시
명사 중심의 URI	URI는 자원을 식별하므로 동사 대신 명사를 사용	❎ /getMember/1 ❎ /deleteMember/1 ✅ /members/1
복수형 사용	자원은 집합 개념이므로 단수보다 복수형 권장	❎ /member/1 ✅ /members/1
계층 관계 표현	/를 사용해 자원 간 포함 관계를 표현	/sports/soccer/players/13

URI 가독성을 높이는 5가지 규칙

원칙	설명	예시
마지막 슬래시(/) 미포함	URI 끝에 /를 붙이지 않아 혼란 방지	❎ /members/ ✅ /members
하이픈(-) 사용	가독성을 위해 단어 구분 시에만 사용	/user-profile
밑줄(_) 미사용	가독성이 떨어지므로 사용 지양	❎ /user_profile ✅ /user-profile
소문자 사용	대소문자 혼동 방지를 위해 소문자 사용	❎ /Members ✅ /members
확장자 미포함	데이터 형식은 헤더로 전달, URI에 포함하지 않음	❎ /members.json ✅ /members

HTTP Method를 통한 행위 정의

자원이 명확히 정의되었다면, 그 자원을 어떻게 조작할지는 HTTP Method라는 전용 도구에 맡깁니다.

Method	역할	예시
GET	리소스 조회 (Read)	/members/1
POST	리소스 생성 (Create)	/members
PUT	리소스 전체 수정 (Update)	/members/1
PATCH	리소스 일부 수정 (Update)	/members/1
DELETE	리소스 삭제 (Delete)	/members/1

RESTful API

앞서 살펴본 것처럼 REST는 단순한 기술이나 도구가 아니라, 웹의 구조를 기반으로 한 아키텍처 스타일이며 여러 가지 제약 조건을 만족해야만 진정한 의미의 REST라고 할 수 있지만 실제 개발 환경에서는 이러한 모든 제약 조건을 완벽하게 지키기 어려운 경우가 많고, 그 대신 REST의 설계 원칙을 최대한 따르는 형태로 API를 구현하게 되는데 이러한 방식을 RESTful API라고 부릅니다.

즉, RESTful API란 REST의 원칙을 완전히 충족하지는 않더라도 자원 중심의 URI 설계와 HTTP Method를 활용한
행위 정의 등 핵심적인 규칙을 따르며, 보다 직관적이고 일관성 있는 API를 만들기 위한 실용적인 접근 방식이라고 볼 수 있습니다.

그래서 어떻게 쓰라고?

결국 RESTful은 이상적인 설계 기준에 가깝지만, 실제 개발에서는 모든 제약 조건을 완벽하게 지키기보다는
핵심 원칙을 기반으로 상황에 맞게 적용하는 것이 중요하며, 무조건적인 규칙 준수보다는 일관성과 가독성, 그리고
유지보수성을 고려한 설계가 더 현실적인 접근 방식이라고 볼 수 있습니다.

특히 대부분의 서비스에서는 Self-descriptive, HATEOAS와 같은 고수준 제약 조건까지 모두 적용하기보다는,
자원 중심의 URI 설계와 HTTP Method를 활용한 행위 정의와 같은 기본 원칙을 중심으로 API를 구성하게 되며,
이러한 수준만 잘 지켜도 충분히 실용적인 REST API를 설계할 수 있습니다.

따라서 REST를 완벽히 구현하려는 것에 집중하기보다는, 핵심적인 설계 원칙을 이해하고 프로젝트의 성격에 맞게
유연하게 적용하는 것이 중요하며 이를 정리해보면 다음과 같습니다.

적용 기준	설명
URI 설계	명사 중심, 복수형, 계층 구조 유지
HTTP Method	GET, POST, PUT, DELETE 역할에 맞게 사용
일관성	URI 규칙과 응답 구조를 일관되게 유지
단순성	불필요한 복잡한 규칙(HATEOAS 등)은 상황에 따라 선택

마무리

REST API와 RESTful API를 정리하면서 느낀 핵심을 다시 정리해보면 다음과 같습니다.

1. REST는 단순한 API 설계 방식이 아니라 웹의 구조와 HTTP 프로토콜을 기반으로 한 아키텍처 스타일이며, 별도의 인프라 없이도 직관적인 데이터 통신 구조를 만들 수 있습니다.
2. 자원을 명사(URI)로 정의하고 행위를 HTTP Method로 분리함으로써, 별도의 명세 없이도 의도를 파악할 수 있는
   일관된 인터페이스를 설계할 수 있습니다.
3. 무상태성(Stateless)과 계층화 구조를 통해 서버와 클라이언트 간의 결합도를 낮추고, 확장성과 유지보수성을
   높일 수 있습니다.
4. RESTful은 이러한 원칙을 완벽히 구현하는 이상적인 개념이지만, 실제로는 모든 제약 조건을 100% 지키기보다는 핵심 원칙을 기반으로 상황에 맞게 적용하는 것이 더 현실적인 접근 방식이라는 점을 이해할 수 있었습니다.