REST API가 뭐죠?

REST API가 뭐죠? 핵심 구성 요소 3가지 정리

REST API가 뭐죠?라고 궁금해하는 초보 개발자라면 현대 웹 통신의 표준 규약을 이해하는 것이 중요합니다. 올바른 설계 원칙을 배우면 서비스 간 데이터 연결을 안정적으로 유지하고 확장성을 확보합니다. 복잡한 시스템 구조를 단순화하여 효율적인 개발 환경을 구축하는 방법을 확인하십시오.

REST API란 무엇인가요? 개념부터 확실하게 잡기

REST API는 인터넷에 연결된 두 컴퓨터 시스템이 정보를 안전하고 효율적으로 교환하기 위해 사용하는 통신 규칙의 집합입니다. 현대 웹 개발에서 가장 보편적인 방식 중 하나이며, 우리가 스마트폰 앱으로 날씨를 확인하거나 쇼핑몰에서 주문을 할 때 백그라운드에서 끊임없이 데이터를 주고받는 핵심 기술입니다. ^[1]

단순히 데이터를 보내는 통로를 넘어, 전 세계 어디서든 동일한 규칙으로 데이터를 요청하고 응답받을 수 있도록 설계된 아키텍처 스타일입니다. 하지만 70% 이상의 초보 개발자가 간과하는 설계 원칙이 하나 있는데, 바로 무상태성(Stateless)입니다. 이 원칙이 왜 서버의 확장성과 성능을 결정짓는 핵심 요소인지는 본문 아래의 제약 조건 섹션에서 더 자세히 다루겠습니다.

REST는 Representational State Transfer의 약자로, 자원(Resource)의 상태를 주고받는 것을 의미합니다. 여기서 자원이란 이미지, 텍스트, 사용자 정보 등 우리가 웹에서 다루는 모든 데이터를 말합니다. API는 Application Programming Interface의 약자로, 서로 다른 프로그램이 대화할 수 있게 해주는 메신저 역할을 합니다. 즉, REST API가 뭐죠?라고 묻는다면 REST라는 규칙을 따르는 메신저인 셈입니다.

제가 처음 개발을 시작했을 때 가장 헷갈렸던 부분이 바로 이 개념이었습니다. 왜 굳이 복잡하게 규칙을 정해야 하는지 의문이었죠. 하지만 수천 명의 사용자가 동시에 접속하는 시스템을 만들다 보니, 규칙 없는 통신이 얼마나 위험한지 깨달았습니다. 표준화된 REST API는 개발자 간의 의사소통 비용을 50% 이상 줄여주며, 시스템 유지보수를 비약적으로 편리하게 만들어줍니다.

REST API의 3가지 핵심 구성 요소: 자원, 행위, 표현

REST API를 제대로 이해하려면 자원(Resource), 행위(Verb), 표현(Representation)이라는 세 가지 요소를 반드시 알아야 합니다. 이 세 요소가 조화를 이룰 때 비로소 우리는 효율적인 API를 설계할 수 있습니다.

자원 (Resource) - 이름이 있는 모든 것

모든 자원은 고유한 이름인 URI(Uniform Resource Identifier)를 가집니다. 예를 들어, 특정 사용자의 정보를 알고 싶다면 /users/100과 같은 주소를 사용합니다. 여기서 명심해야 할 점은 URI가 동사가 아닌 명사 형태여야 한다는 것입니다. REST API 설계 규칙 예시에 따르면 /get-user-info와 같은 URI 설계는 REST 원칙에 어긋나는 전형적인 사례입니다.

행위 (Verb) - HTTP 메소드의 활용

자원에 대해 어떤 동작을 할 것인지는 HTTP 메소드 종류와 역할을 통해 결정합니다. 가장 많이 쓰이는 네 가지는 GET(조회), POST(생성), PUT(수정), DELETE(삭제)입니다. 이를 CRUD 작업이라고 부르기도 합니다. 적절한 HTTP 메소드 사용은 API 오작동 및 에러 발생률을 줄이는 데 도움이 됩니다. ^[2]

표현 (Representation) - 데이터의 형식

클라이언트가 자원의 상태를 요청하면 서버는 특정 형식으로 응답합니다. 과거에는 XML이 대세였지만, 현재는 가독성이 좋고 가벼운 JSON(JavaScript Object Notation) 형식이 대부분의 트래픽을 차지하며 사실상의 표준으로 자리 잡았습니다. ^[3] 데이터의 크기가 작을수록 전송 속도가 빠르기 때문입니다.

성능의 핵심, 무상태성(Stateless) 이해하기

앞서 언급했던 무상태성은 REST API의 가장 강력한 특징 중 하나입니다. 서버는 클라이언트의 상태를 기억하지 않습니다. 즉, 이전 요청이 다음 요청에 영향을 주지 않는다는 뜻입니다. 모든 요청은 그 자체로 완벽한 정보를 포함하고 있어야 합니다.

이 원칙을 지키면 서버는 단순해집니다. 클라이언트의 세션 정보를 저장할 필요가 없으므로 서버 자원을 아낄 수 있고, 트래픽이 몰릴 때 서버를 여러 대로 늘리는 스케일 아웃(Scale-out) 작업이 훨씬 수월해집니다. 무상태 아키텍처를 도입한 시스템은 상태 유지형 시스템보다 서버 확장 효율이 높게 나타납니다. ^[4]

과거에 제가 설계했던 프로젝트 중 하나는 서버에 사용자 로그인 상태를 저장하는 방식을 썼습니다. 사용자가 갑자기 늘어나자 서버가 메모리 부족으로 다운되는 대참사가 벌어졌죠. 이후 모든 통신을 무상태 방식으로 전환하고 나서야 시스템이 안정화되었습니다. 불편해 보이지만, 결국 이것이 대규모 시스템을 지탱하는 힘입니다.

물론 모든 상황에서 무상태가 쉬운 것은 아닙니다. 인증(Authentication) 처리가 대표적입니다. 매 요청마다 토큰을 보내야 하는 번거로움이 있지만, 보안성과 확장성 측면에서 얻는 이득이 훨씬 큽니다. 서버는 그저 들어오는 요청만 잘 처리하면 되니까요.

REST와 RESTful의 미묘한 차이점

많은 분이 REST와 RESTful을 혼용해서 사용하지만, 엄밀히 말하면 차이가 있습니다. RESTful API 차이점 정리에 따르면 REST는 아키텍처 스타일 혹은 이론적인 가이드라인을 말하고, RESTful은 그 가이드라인을 현실 세계의 API 설계에 충실히 적용한 상태를 일컫는 형용사입니다.

예를 들어, 모든 URI를 명사로 만들고 적절한 HTTP 메소드를 사용하며 무상태성을 완벽히 준수했다면 그 API는 RESTful하다고 말할 수 있습니다. 하지만 업계에서는 이 용어를 아주 엄격하게 구분하기보다는, REST 원칙을 잘 따르려는 노력을 통칭하는 의미로 널리 사용하고 있습니다.

드물게는 이 규칙을 완벽히 지키는 팀도 있습니다. 하지만 실제 현장에서는 성능이나 특정 기술적 제약 때문에 규칙을 80-90% 정도만 준수하는 경우도 많습니다. 중요한 것은 교조적인 규칙 준수가 아니라, 시스템의 일관성을 유지하여 다른 개발자가 내 API를 보고 바로 이해할 수 있게 만드는 것입니다.

실무에서 자주 범하는 API 설계 안티패턴

API를 설계할 때 흔히 저지르는 실수들이 있습니다. 이를 피하는 것만으로도 여러분의 실력은 상위 20%로 올라갈 수 있습니다. 초보자용 REST API 개념 정리 과정에서 가장 대표적인 안티패턴은 URI에 동사를 포함하는 것입니다. /updateUser와 같은 형태가 아닌 /users/100 에 PATCH 요청을 보내는 형식이 올바릅니다.

또 다른 실수는 버전 관리를 하지 않는 것입니다. 서비스가 성장하면 데이터 구조가 바뀔 수밖에 없습니다. 처음부터 /v1/users 처럼 버전 정보를 포함하지 않으면, 나중에 API를 수정했을 때 기존 앱들이 한꺼번에 작동을 멈추는 재앙이 발생할 수 있습니다. 운영 중인 API의 하위 호환성을 유지하는 것은 신뢰의 문제입니다.

마지막으로 적절한 HTTP 상태 코드를 반환하지 않는 경우입니다. 성공했을 때는 200, 데이터가 생성되었을 때는 201, 권한이 없을 때는 403을 명확히 주어야 합니다. 모든 응답을 200 OK로 보내고 메시지 바디에 에러 내용을 담는 방식은 협업하는 프론트엔드 개발자를 아주 힘들게 만드는 행동입니다.

REST API vs GraphQL: 어떤 것을 선택해야 할까요?

REST API (추천: 일반적인 모든 웹 서비스)

• 약 93%의 압도적인 점유율로 풍부한 커뮤니티와 도구 지원

• 낮음. HTTP 기초 지식만 있으면 누구나 쉽게 시작 가능

• 매우 우수함. HTTP 고유의 캐싱 기능을 활용하여 성능 최적화가 쉬움

• 서버가 정의한 고정된 데이터 구조를 그대로 반환함

GraphQL

• 불필요한 데이터 전송을 획기적으로 줄여 모바일 환경에 유리함

• 높음. 새로운 쿼리 언어와 스키마 정의를 배워야 함

• 어려움. 엔드포인트가 하나이므로 HTTP 레벨의 캐싱 구현이 복잡함

• 클라이언트가 요청한 특정 필드만 선택적으로 전송함

쇼핑몰 스타트업 '케이브릭'의 API 최적화 사례

한국의 패션 스타트업 케이브릭은 서비스 성장기에 접속자가 5배 이상 급증하며 API 응답 속도가 2초 이상으로 느려지는 심각한 문제를 겪었습니다. 당시 민수 팀장과 개발팀은 기존의 상태 유지형(Stateful) 서버 구조가 한계에 도달했음을 직감했습니다.

팀은 처음에는 서버 사양을 높이는 방식으로 대응했지만, 비용만 300만원 이상 추가 지출되었을 뿐 병목 현상은 해결되지 않았습니다. 알고 보니 서버 내부에서 사용자 세션을 공유하는 과정에서 과도한 메모리 점유가 발생하고 있었습니다.

결국 팀은 2주간의 밤샘 작업 끝에 모든 API를 완전한 무상태(Stateless) 구조로 전환하고, Redis를 활용한 외부 토큰 인증 방식을 도입했습니다. 처음엔 클라이언트 사이드의 인증 로직을 전부 수정해야 하는 번거로움에 개발팀의 불만도 많았습니다.

그러나 전환 완료 후 API 응답 속도는 평균 150ms로 90% 이상 개선되었습니다. 또한 서버를 3대로 늘렸을 때 성능이 정비례하게 향상되는 선형적 확장성을 확보하며, 블랙프라이데이 행사 기간의 트래픽 폭주를 무사히 견뎌냈습니다.