[TIL] 250506_Web: RESTful API

지코·2025년 5월 6일

Today I Learned

목록 보기

64/66

📌 RESTful API는 무엇인가?

RESTful API는 REST(REpresentational State Transfer) 스타일을 준수하여 설계된 API를 의미한다. 여기서 REST는 웹의 리소스를 클라이언트와 서버가 일관된 방식으로 처리할 수 있도록 하는 설계 원칙이다. 좀 더 정확한 표현으로 말하자면, REST는 Resource Oriented Architecture 이다. API 설계의 중심에 자원이 있고, HTTP Method를 통해 자원을 처리하도록 설계하는 것이다.

기본적으로 REST에서는 리소스를 고유한 URI로 표현하고, HTTP 메서드(GET(조회) , POST(생성) , PUT(수정) , DELETE(삭제) 등)를 사용해 행위를 표현한다.
예를 들어 /users URI에 GET 요청을 보내면 사용자 목록을 가져오는 API로 동작할 수 있다.

🤔 REST & RESTful이란?

REST란, REpresentational State Transfer의 약자로, 웹의 장점을 최대한 활용할 수 있는 클라이언트와 서버 간 통신 방식 중 하나이다.

설계 기본 규칙으로 HTTP URI를 통해 자원을 명시하고, HTTP method(GET, POST, DELETE, PUT)을 통해 자원을 처리하도록 설계된 아키텍처이다.

RESTful은 REST라는 아키텍처를 구현하는 웹 서비스를 나타내는 것으로, REST 원리를 따르는 시스템을 RESTful이라는 용어로 지칭한다.

🤔 왜 RESTful API를 사용할까?

REST는 웹의 HTTP 표준을 그대로 활용하기 때문에, 개발자 간 커뮤니케이션이 효율적이다. RESTful API는 시스템 간의 통신을 단순화하고, 확장성과 유지보수성을 높이기 위해 사용한다.

RESTful API 외에도 GraphQL, gRPC 같은 방식들도 있지만, REST는 구현이 쉽고 러닝 커브가 낮아 널리 쓰인다.

❓ GET 방식과 POST 방식의 차이점 ⭐️

➡️ 데이터를 어디에 담냐 (Header-URL or Body) / 용도(조회 / 생성) / 캐싱 가능 여부

GET과 POST는 모두 HTTP 프로토콜을 이용해 서버에 무엇인가를 요청할 때 사용하는 방식이다.

📌 데이터 전송 방식

GET 방식은 HTTP Request Message 의 Header 부분에 URL에 쿼리 파라미터를 붙여서 데이터를 보낸다.
이러한 방식은 정보가 URL이라는 공간에 담겨서 가기 때문에 전송할 수 있는 데이터의 크기가 제한적이다. 또한 민감한 정보가 URL에 노출되기 때문에, 민감한 정보 전송에 적합하지 않다.
반대로 POST 요청은 HTTP Request Message의 URL이 아닌 body에 데이터를 담아 전송한다.
따라서 담을 수 있는 데이터 크기가 GET 방식보다 크고, 보안에 조금 더 적합하다.

📌 용도

GET 방식은 서버에서 데이터를 가져와서 보여주는 용도이며, 서버의 값이나 상태 등을 변경하지는 않는다.
반면 POST 방식은 서버의 값이나 상태를 변경하기 위해, 추가하기 위해 사용된다.

📌 캐싱

GET 방식의 요청은 브라우저에서 캐싱(Caching)이 가능하다.
때문에 POST 방식으로 요청해야 할 것을 보내는 데이터의 크기가 작고 보안적인 문제가 없다는 이유로 GET 방식으로 요청한다면, 기존에 캐싱되어있던 데이터가 응답될 가능성이 존재한다❗️

❓ POST 방식과 PUT 방식의 차이

POST 는 보통 INSERT의 개념으로 사용되고, PUT 은 UPDATE의 개념으로 생각하면 이해하기 쉽다.
또한 POST 는 멱등하지 않고, PUT 은 멱등하다. 즉 동일한 자원을 여러 번 POST 하면 서버 자원에는 변화가 생기지만, 여러 번 PUT 하는 경우에는 변화가 생기지 않는다.

❓ PUT 방식과 PATCH 방식의 차이

PUT 이 해당 자원의 전체를 교체하는 의미를 지닌 대신, PATCH 는 일부를 변경한다는 의미를 가진다. 또한 PUT 의 경우는 멱등하지만, PATCH 의 경우 멱등하지 않다. PUT 은 전체 자원을 업데이트하기 때문에, 동일 자원에 대해 동일하게 PUT 을 처리하는 경우 멱등하게 처리된다. 하지만 PATCH 로 처리되는 경우, 자원의 일부가 변경되기 때문에 멱등성을 보장할 수 없다.

🤔 왜 POST 방식이 더 비용이 많이 들까?

캐싱이 안됨

GET은 동일한 요청이면 브라우저나 프록시 서버가 캐싱해서 빠르게 처리할 수 있다.
POST는 동일한 요청이어도 매번 서버로 전달되기 때문에, 캐싱의 이점이 없다. → 데이터 처리 비용이 증가한다.

데이터가 본문(body)에 포함됨

서버는 요청의 body를 파싱해야 하므로 GET보다 처리 비용이 더 들 수 있다.
특히 큰 payload(ex> 파일 업로드나 복잡한 JSON 데이터)일 경우 비용이 확실히 크다.

🤔 그래도 왜 POST를 사용할까?

비용이 더 들더라도, 기능상 필요하기 때문이다.

데이터를 생성하거나 변경해야 할 때. (ex> 회원가입, 댓글 작성, 주문 생성 등)

서버 상태를 변경해야 하므로 반드시 POST 요청으로 해야 한다.
GET은 읽기만 가능하다.

민감한 데이터를 안전하게 보내기 위해 필요.

로그인 시 아이디/비밀번호 전송.
POST 방식은 정보가 body에 담겨 상대적으로 더 안전하다.

보낼 데이터가 많을 때.

GET 방식은 URL 길이 제한이 있지만, POST는 본문에 데이터를 담기 때문에 훨씬 많은 양의 데이터를 전송하는 것이 가능하다.

요청이 자주 바뀌는 작업에 적합.

검색 필터나 설정 변경 같은 복잡한 요청은 POST가 더 유연하다.

📌 REST의 핵심 규칙들

클라이언트-서버 분리: 클라이언트와 서버 간의 역할을 명확히 분리한다.
REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보 등) 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에, 각각 개발해야 할 내용이 명확해지고 서로 간의 의존성이 줄어들게 된다.
무상태성(Stateless): 서버는 클라이언트의 상태를 저장하지 않으며, 각 요청은 독립적으로 처리한다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에, API 서버는 들어오는 요청만을 단순히 처리하면 된다. 덕분에 서비스의 자유도가 높아지고, 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.
일관된 인터페이스(Uniform Interface): 고유한 URI로 리소스를 식별하고, 일관된 인터페이스를 통해 클라이언트와 서버가 간단하고 예측 가능하게 통신할 수 있도록 한다.
캐시 가능성: HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 인프라를 그대로 활용할 수 있다. 따라서 HTTP가 가진 캐싱 기능이 적용 가능하다.
자체 표현 구조(Self-Descriptiveness): REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어 있다.
계층형 구조: REST 서버는 다중 계층으로 구성될 수 있으며, 보안, 로드 밸런싱, 암호화 계층을 추가해 구조 상의 유연성을 둘 수 있고, PROXY, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있게 한다.

🤔 RESTful하게 API를 디자인한다는 것은 무엇인가?

리소스와 행위를 명시적이고 직관적으로 분리한다.

리소스는 URI 로 표현되는데, 리소스가 가리키는 것은 명사 로 표현되어야 한다.
행위는 HTTP Method 로 표현하고, GET(조회) , POST(생성) , PUT(수정) , DELETE(삭제) 를 명확한 목적으로 사용한다.

Message는 Header와 Body를 명확하게 분리해서 사용한다.

Entity에 대한 내용은 Body에 담는다.
애플리케이션 서버가 행동할 판단의 근거가 되는 컨트롤 정보인 API 버전 정보, 응답 받고자 하는 MIME 타입 등을 header에 담는다.
header와 body는 http header와 http body로 나눌 수도 있고, http body에 들어가는 json 구조로 분리할 수도 있다.