REST API

REST API란 무엇인가

REST(Representational State Transfer)는 자원을 URI로 표현하고 HTTP의 기본 동작으로 다루는 웹 API 설계 원칙이다. 시스템이 다루는 모든 대상, 곧 회원·주문·상품 같은 것을 자원으로 보고 각각에 고유한 주소를 부여한 뒤, 그 주소에 대해 정해진 행위를 적용하는 방식이다.

별도의 복잡한 규약 없이 웹의 기존 기반인 HTTP를 그대로 활용하므로 이해하기 쉽고 호환성이 높다. 이 단순함과 표준 친화성 덕분에 REST는 현대 웹·모바일 서비스 연동의 사실상 기본 방식으로 자리 잡았다.

자원과 행위의 분리

REST의 핵심은 무엇을 다룰지와 어떻게 다룰지를 명확히 나누는 데 있다. 자원은 URI로, 그 자원에 가하는 행위는 HTTP 메서드로 표현한다.

조회·생성·수정·삭제 같은 작업을 각각의 메서드에 대응시키면, 주소만 보고도 어떤 자원을 다루는지, 메서드만 보고도 어떤 동작인지 직관적으로 읽힌다. 동사를 URI에 섞어 넣는 대신 자원은 명사로, 동작은 메서드로 분리하는 규율이 REST 설계의 출발점이다.

무상태성이라는 원칙

REST는 서버가 클라이언트의 이전 요청 상태를 기억하지 않는 무상태성을 중요한 제약으로 둔다. 각 요청은 처리에 필요한 정보를 스스로 담고 있어야 하며, 서버는 그 요청만 보고 독립적으로 응답한다.

이렇게 하면 어느 서버가 요청을 받아도 같은 결과를 내므로, 서버를 수평으로 늘려 부하를 분산하기가 쉬워진다. 다만 인증 정보나 맥락을 매 요청에 실어 보내야 하므로, 토큰 기반 인증처럼 상태를 클라이언트가 들고 다니는 설계와 자연스럽게 맞물린다.

성숙도와 흔한 오해

실무에서 REST를 표방하지만 원칙을 절반만 따르는 경우가 많다. 자원을 URI로 나누었더라도 모든 동작을 한두 가지 메서드로만 처리하거나, 응답 코드를 일관되게 쓰지 않으면 REST의 이점이 흐려진다.

흔한 오해는 단순히 HTTP로 데이터를 주고받으면 모두 REST라고 여기는 것이다. 자원 중심의 주소 체계, 메서드의 의미에 맞는 사용, 일관된 상태 코드라는 약속이 함께 지켜질 때 비로소 호출하는 쪽이 추측 없이 API를 사용할 수 있다.

SOA·MSA에서의 위치

REST API는 SOA나 MSA에서 서비스 사이를 잇는 통신 수단으로 폭넓게 쓰인다. 과거의 무거운 통합 방식과 달리, REST는 가벼운 HTTP 기반이라 서로 다른 언어와 플랫폼으로 만든 서비스를 손쉽게 연결한다.

잘게 나뉜 서비스가 명확한 자원 모델과 계약으로 서로를 호출하면, 각 서비스를 독립적으로 개발하고 배포하기가 수월해진다. 이런 이유로 REST는 분산된 서비스 구조에서 서비스 간 계약을 표현하는 표준적인 인터페이스 역할을 맡는다.

설계 시 점검 사항

REST API의 품질은 일관성에서 갈린다. 자원 이름, 메서드 사용, 오류 응답 형식이 엔드포인트마다 들쭉날쭉하면, 소비자는 매번 문서를 뒤지며 예외를 익혀야 한다.

또한 외부에 공개된 API는 한번 자리 잡으면 바꾸기 어려우므로, 변경에 대비한 버전 관리 전략을 처음부터 세워 두어야 한다. 자원 경계를 너무 잘게 쪼개면 한 화면을 그리는 데 여러 번 호출해야 하고, 너무 거칠게 묶으면 불필요한 데이터가 따라온다.

호출자의 실제 사용 흐름을 기준으로 자원의 입도를 정하는 균형 감각이 좋은 API 설계의 관건이다.