REST API 입문: 개념부터 실제 요청까지, 웹을 움직이는 데이터 통신의 원리

오늘날 웹 서비스와 모바일 애플리케이션의 상당수는 화면 뒤편에서 끊임없이 데이터를 주고받으며 동작한다. 이 데이터 교환의 표준적인 방식으로 가장 널리 자리 잡은 것이 바로 REST API이다. REST API는 서로 다른 시스템이 일관된 규칙 아래에서 자원을 조회하고 생성하며 수정할 수 있도록 돕는 인터페이스로, 백엔드 개발의 기본기이자 프론트엔드와 서버를 잇는 핵심 구조로 평가된다. 이 글은 REST의 정의와 등장 배경에서 출발해, 그것을 지탱하는 핵심 원칙과 HTTP 메서드의 활용, 요청과 응답의 실제 구조, 그리고 URI 설계 방식까지 단계적으로 정리한다. 개념을 처음 접하는 입문자가 실제 요청이 어떻게 흘러가는지를 명확한 기준으로 이해할 수 있도록 서술하는 데 목적이 있다.

 

 

 

 

 

 

 

 

▍ REST API란 무엇인가: 정의와 등장 배경

 

REST는 Representational State Transfer의 약자로, 2000년 로이 필딩(Roy Fielding)의 박사학위 논문에서 처음 소개된 개념이다. 필딩은 HTTP 규격을 정립하는 데 참여한 인물 중 하나였고, 당시 웹이 지닌 설계적 우수성이 충분히 활용되지 못하는 상황에 문제의식을 느껴 웹의 장점을 최대한 살리기 위한 아키텍처 스타일로 REST를 제안한 것으로 알려져 있다. 여기서 주목할 점은 REST가 특정 기술이나 프로그램이 아니라 하나의 아키텍처 스타일, 즉 시스템을 설계할 때 따르는 원칙의 집합이라는 사실이다.

 

REST API는 이러한 REST 원칙을 따르는 API를 가리킨다. API 자체는 서로 다른 소프트웨어가 정보를 주고받기 위해 약속한 규약 전반을 의미하며, REST는 그 규약을 설계할 때 채택하는 하나의 방식이다. REST API의 가장 큰 특징은 웹의 표준 규칙인 HTTP를 그대로 활용해 서비스의 데이터와 기능을 외부로 제공한다는 데 있다. 이 덕분에 REST API는 별도의 특수한 통신 인프라를 구축할 필요 없이, HTTP를 지원하는 모든 플랫폼에서 폭넓게 호환된다는 범용성을 갖는다.

 

 

 

▍ 자원 중심 설계: REST의 출발점

 

REST의 핵심 사고방식은 세상의 모든 대상을 자원(Resource)으로 바라보는 데서 출발한다. 회원, 주문, 상품, 게시글처럼 이름을 붙일 수 있는 모든 것이 자원이 될 수 있으며, 각 자원은 고유한 식별자인 URI(Uniform Resource Identifier)로 지목된다. 예를 들어 특정 사용자를 나타내는 자원은 /users/123과 같은 주소로 표현할 수 있다. REST 아키텍처에서는 하나의 자원이 원칙적으로 하나의 URI에 대응하도록 설계하며, 그 자원에 대한 모든 접근이 해당 주소를 통해 이루어지도록 한다.

 

이러한 자원 중심 접근은 실무에서 중요한 함의를 갖는다. 데이터를 다루는 관점을 '무엇을 할 것인가(동작)'가 아니라 '무엇을 대상으로 하는가(자원)'로 전환하기 때문이다. 자원을 명확히 정의하고 나면, 그 자원에 가하는 조회·생성·수정·삭제 같은 행위는 뒤에서 설명할 HTTP 메서드가 담당하게 된다. 결과적으로 같은 자원에 대한 여러 작업이 하나의 일관된 주소 체계 안에서 통합되어, 웹 프론트엔드와 모바일 앱, 외부 파트너 시스템이 모두 동일한 방식으로 서비스에 접근할 수 있게 된다.

 

 

 

 

 

 

▍ REST를 지탱하는 여섯 가지 원칙

 

REST가 하나의 아키텍처 스타일로 성립하기 위해서는 몇 가지 제약 조건을 충족해야 한다. 이 원칙들은 서로 맞물려 확장성과 유지보수성을 높이는 방향으로 작동한다.

 

 

 

▍ 클라이언트-서버 구조

 

자원을 요청하는 쪽인 클라이언트와 자원을 제공하는 쪽인 서버가 명확히 분리되어야 한다. 클라이언트는 사용자와 관련된 처리를 담당하고 서버는 자원과 데이터를 관리하는 역할에 집중함으로써, 두 영역이 독립적으로 발전할 수 있다. 이러한 역할 분리는 각 구성 요소의 관심사를 명확히 나누어 전체 구조를 단순하게 유지하는 기반이 된다.

 

 

 

▍ 무상태성(Stateless)

 

REST에서 서버는 클라이언트의 상태를 저장하지 않는다. 각 요청은 그 자체로 처리에 필요한 모든 정보를 담고 있어야 하며, 서버는 이전 요청의 맥락을 기억하지 않고 개별 요청을 완전히 독립적인 것으로 처리한다. 이 원칙 덕분에 서버 구현이 단순해지고, 요청이 늘어날 때 여러 서버로 부하를 나누는 확장이 용이해진다. 다만 이전 요청이 데이터베이스를 변경해 그 결과가 이후에 반영되는 것은 무상태성과 별개의 문제로, 허용되는 동작이다.

 

 

 

▍ 캐시 처리 가능성

 

REST는 웹 표준 HTTP를 그대로 사용하므로 HTTP가 지닌 강력한 기능인 캐싱을 적용할 수 있다. 응답을 적절히 캐시하면 동일한 요청에 대한 반복적인 처리를 줄여 응답 시간을 단축하고 서버 자원의 이용 효율을 높일 수 있다.

 

 

 

▍ 통일된 인터페이스

 

REST의 이름에서 알 수 있듯 가장 상징적인 원칙은 통일된 인터페이스이다. URI로 지정한 자원에 대한 조작을 통일되고 한정적인 방식으로 수행함으로써, 클라이언트는 일관된 규칙만 익히면 어떤 자원이든 같은 방식으로 다룰 수 있다. 이 일관성은 특정 언어나 기술에 종속되지 않는다는 점에서 REST의 범용성을 뒷받침한다.

 

 

 

▍ 계층화 구조와 코드 온 디맨드

 

클라이언트와 서버 사이에 프록시 서버나 암호화 계층 같은 중간 매개체를 둘 수 있으며, 클라이언트는 자신이 최종 서버와 통신하는지 중간 계층과 통신하는지 알 필요가 없다. 이러한 계층화는 보안과 부하 분산 측면에서 자유도를 높인다. 여기에 더해, 필요할 경우 서버가 실행 가능한 코드를 클라이언트에 전달해 기능을 확장하는 선택적 원칙도 존재한다.

 

 

 

▍ HTTP 메서드와 CRUD의 대응

 

REST에서 자원의 위치는 URI가, 자원에 대한 행위는 HTTP 메서드가 담당한다. 데이터를 다루는 기본 동작인 생성(Create), 조회(Read), 수정(Update), 삭제(Delete), 즉 CRUD는 주요 HTTP 메서드와 자연스럽게 짝을 이룬다. 아래 표는 그 대응 관계를 정리한 것이다.

 

 

 

 

이 구분이 갖는 실질적 가치는 요청 메시지만 보고도 그 의도를 파악할 수 있다는 점에 있다. 예컨대 GET /users는 사용자 목록을 조회하는 요청이고, POST /users는 새로운 사용자를 등록하는 요청이라는 사실이 주소와 메서드의 조합만으로 명확하게 드러난다. 자원 URI는 그대로 두고 행위만 메서드로 바꾸는 이 방식은, 같은 자원에 대한 다양한 작업을 하나의 규칙 안에서 일관되게 표현하도록 돕는다.

 

 

 

 

 

 

▍ 요청과 응답의 실제 구조

 

REST API를 통한 통신은 클라이언트가 요청(Request)을 보내고 서버가 응답(Response)을 반환하는 흐름으로 이루어진다. 요청과 응답은 모두 헤더(Header)와 본문(Body)이라는 두 부분으로 구성된다. 헤더에는 어떤 요청인지 또는 어떤 응답인지를 설명하는 부가 정보가 담기고, 본문에는 실제로 주고받는 데이터가 들어간다.

 

요청 헤더에는 요청 주소와 브라우저 정보, 인증 토큰 같은 내용이 포함되며, 요청 본문에는 로그인 정보나 등록하려는 데이터가 실린다. 응답의 경우 헤더에 성공 여부와 데이터 형식 등의 요약 정보가, 본문에는 실제 결과 데이터가 담긴다. REST API가 데이터를 표현하는 대표적인 형식은 JSON으로, 사람이 읽기에도 직관적이고 다양한 프로그래밍 언어에서 다루기 편리하다는 이유로 폭넓게 사용된다.

 

 

 

▍ 상태 코드로 결과를 알리는 방식

 

서버는 요청 처리 결과를 HTTP 상태 코드라는 숫자로 클라이언트에 전달한다. 상태 코드는 세 자리 숫자의 첫 자리에 따라 큰 범주가 나뉘며, 이를 적절히 활용하면 클라이언트에게 상황을 명확하게 전달할 수 있다. 다음은 자주 접하는 상태 코드를 정리한 것이다.

 

 

 

 

상태 코드의 사용에는 세심한 고려가 필요하다. 예를 들어 데이터가 존재하지 않는 상황을 200으로 응답할지 404로 응답할지를 두고 실무에서 논의가 갈리는 경우가 있다. 자원 자체가 존재하지 않는 경우와, 조회 조건에 맞는 데이터가 단지 비어 있는 경우를 구분해야 하기 때문이다. 이처럼 상태 코드는 단순한 관습이 아니라 클라이언트가 상황을 정확히 해석하도록 돕는 약속이라는 점에서, 일관된 기준을 세우는 것이 중요하다.

 

 

 

▍ URI 설계의 기본 규칙

 

REST API의 완성도는 URI를 얼마나 일관되고 직관적으로 설계하느냐에 크게 좌우된다. 잘 정리된 명명 규칙은 문서를 꼼꼼히 읽지 않아도 요청 방식을 예측할 수 있게 해 사용자 경험을 높인다. 널리 통용되는 설계 관행은 다음과 같다.

 

첫째, URI는 동사가 아니라 명사로 자원을 표현한다. /getUsers처럼 동작을 주소에 담는 대신 /users로 표현하고, 동작은 HTTP 메서드로 나타낸다. 둘째, 컬렉션을 나타내는 자원은 관행적으로 복수형을 사용한다. 셋째, 자원 간의 계층 관계는 슬래시(/)로 표현하되, URI 끝에 슬래시를 붙이지 않는다. 예를 들어 특정 사용자의 주문 목록은 /users/123/orders와 같이 계층적으로 표현할 수 있다. 넷째, 주소가 길어질 때는 가독성을 위해 하이픈(-)으로 단어를 구분하는 편이 권장된다. 다섯째, 검색이나 필터링, 정렬처럼 자원을 조건에 따라 걸러내는 작업은 새로운 주소를 만들기보다 쿼리 파라미터를 활용한다. /users?region=ko처럼 물음표 뒤에 조건을 붙이는 방식이 그 예이다.

 

 

 

 

 

 

▍ REST와 다른 방식의 비교

 

REST가 웹 API 설계의 사실상 표준으로 자리 잡았지만, 유일한 선택지는 아니다. 대표적으로 2015년 공개된 GraphQL은 REST가 지닌 일부 한계를 다른 방식으로 해결하려는 접근이다. REST에서는 필요한 데이터에 비해 지나치게 많은 정보를 받는 오버페칭(over-fetching)이나 필요한 정보가 부족해 여러 번 요청해야 하는 언더페칭(under-fetching) 문제가 발생할 수 있다. GraphQL은 클라이언트가 필요한 데이터를 정확히 명시해 요청함으로써 이러한 문제를 완화한다.

 

다만 두 방식은 우열의 관계라기보다 상황에 따른 선택의 문제로 보는 것이 타당하다. REST는 설계의 단순성과 일관성, 그리고 폭넓은 지원이라는 강점을 지녀 대다수 서비스에 적합하다. 반면 복잡하고 동적인 데이터 요구가 많은 대규모 애플리케이션에서는 GraphQL의 유연성이 이점을 발휘하기도 한다. 실제 프로젝트에서는 전반적으로 REST를 사용하면서 특정 영역에만 GraphQL을 도입하는 혼합 방식을 택하기도 한다. 또한 RESTful API를 구현하는 근본적인 목적이 성능 향상 그 자체가 아니라는 점도 유념할 필요가 있다. 성능이 절대적으로 중요한 경우라면 다른 설계 방식을 고려할 수 있다.

 

 

 

▍ REST API의 장점과 실제 함의

 

REST API가 널리 채택된 이유는 여러 실질적 이점에서 찾을 수 있다. HTTP라는 웹 표준을 그대로 활용하므로 기존 웹 인프라를 재사용할 수 있고, 별도의 통신 규격을 구축할 필요가 없다. 요청 메시지가 그 의도를 명확히 드러내 시스템의 동작을 파악하기 쉬우며, 클라이언트와 서버의 역할이 분명히 분리되어 각 영역을 독립적으로 개발하고 확장할 수 있다. 응답 구조와 에러 처리 형식을 통일하면 클라이언트 코드가 단순해지고 예외 처리 로직을 공통화할 수 있어 유지보수 비용이 줄어든다.

 

동시에 세심하게 고려해야 할 지점도 있다. REST 원칙의 일부만 차용했다고 해서 그 API가 곧바로 RESTful하다고 말할 수는 없으며, 설계 규칙을 올바르고 일관되게 지킬 때 비로소 REST의 가치가 온전히 실현된다. 응답 구조나 에러 형식에 예외가 쌓일수록 구조는 흔들리고, 규칙이 일관되게 유지될수록 확장이 쉬워진다. 이 때문에 실무에서는 초기에 자원 정의와 URI 규칙, 상태 코드 기준을 명확히 잡아두는 작업이 강조된다. 잘 되는 서비스일수록 기능보다 구조가 먼저 정리되어 있다는 평가는 이러한 맥락에서 나온다.

 

 

 

 

 

 

▍ 정리하며

 

REST API는 자원을 URI로 식별하고 그 자원에 대한 행위를 HTTP 메서드로 표현하는, 자원 중심의 일관된 데이터 통신 방식이다. 무상태성과 통일된 인터페이스를 비롯한 원칙들이 서로 맞물려 확장성과 유지보수성을 높이며, 요청과 응답은 헤더와 본문으로 구성되고 상태 코드를 통해 처리 결과가 전달된다. URI를 명사와 복수형, 계층 구조로 일관되게 설계하는 관행은 REST API의 사용성을 크게 좌우한다. 이러한 기본 구조를 이해하면, 웹과 앱이 화면 뒤편에서 어떻게 데이터를 주고받으며 동작하는지가 한결 명확하게 보인다. REST의 원리는 특정 기술에 매이지 않는 설계 철학인 만큼, 개념을 충실히 익힌 뒤 실제 요청을 직접 관찰하고 다뤄 보는 과정을 통해 이해를 한층 깊이 다져 나갈 수 있다.