REST API란
API는 다른 소프트웨어와 통신할 때 따라야 하는 규칙이다. 웹 API는 웹에 있는 클라이언트와 리소스 사이의 관문이다. 클라이언트는 정보를 얻으려는 사용자나 프로그램이고, 리소스는 서버가 제공하는 이미지/텍스트/숫자 같은 모든 종류의 데이터다. REST(Representational State Transfer)는 API가 어떻게 동작해야 하는지 조건을 정한 소프트웨어 아키텍처다. REST 방식을 따르는 API가 REST API이고, REST API와 RESTful API는 같은 뜻으로 쓴다. HTTP 위에서 REST API를 구현하는 경우가 많다.
REST의 원칙
| 원칙 | 내용 |
|---|---|
| 균일한 인터페이스 | 요청은 URI로 리소스를 식별하고, 서버는 표준 형식(표현)으로 정보를 전달한다. 서버는 자기 설명적인 메시지와 하이퍼링크도 함께 보낸다 |
| 무상태(stateless) | 서버가 모든 요청을 이전 요청과 상관없이 독립적으로 처리한다 |
| 계층형 시스템 | 클라이언트와 서버 사이에 중간 계층이 있어도 클라이언트에게는 보이지 않는다 |
| 캐시 가능성 | 응답이 스스로 캐시 가능 여부를 정의하고, 캐시 가능한 응답은 클라이언트나 중간 계층에 저장된다 |
| 주문형 코드 | 서버가 코드를 클라이언트에 보내 기능을 확장한다(예: 입력 오류 표시) |
이 원칙의 장점을 AWS는 세 가지로 설명한다. 무상태라서 서버가 이전 요청 정보를 기억할 필요가 없어 서버 부하가 줄고 확장성이 좋아진다. 클라이언트와 서버를 완전히 분리해서 각 부분이 독립적으로 발전할 수 있어 유연성이 높아진다. 클라이언트와 서버를 서로 다른 언어로 만들어도 API 설계에 영향이 없어 기술에 독립적이다. 전에 HTTP 자체가 상태를 저장하지 않는다고 했는데 REST의 무상태 원칙은 이 성질을 API 설계 규칙으로 가져온 것이다.
요청의 구성
REST API 요청에는 아래 요소가 들어간다.
| 구성 | 설명 |
|---|---|
| 리소스 식별자 | 보통 URL을 쓰고, 요청 엔드포인트라고도 부른다 |
| 메서드 | 서버가 리소스에 무엇을 해야 하는지 알려 주는 HTTP 메서드 |
| 헤더 | 요청과 응답의 형식 같은 메타데이터 |
| 데이터 | POST/PUT 같은 메서드에서 보내는 본문 |
| 파라미터 | 경로 파라미터(URL 상세), 쿼리 파라미터(리소스 추가 정보), 쿠키 파라미터(빠른 인증) |
HTTP 메서드
AWS 문서가 REST에서 흔히 쓰는 네 가지로 GET/POST/PUT/DELETE를 꼽고, MDN은 PATCH를 포함해 각 메서드의 특성을 정리한다. 다섯 가지를 비교하면 이렇다.
| 메서드 | 하는 일 | 안전(safe) | 멱등(idempotent) |
|---|---|---|---|
| GET | 리소스를 조회하고, 본문은 없어야 한다 | 예 | 예 |
| POST | 데이터를 제출해 서버에 변화를 일으킨다 | 아니오 | 아니오 |
| PUT | 대상 리소스의 표현을 요청 내용으로 모두 교체한다 | 아니오 | 예 |
| PATCH | 리소스의 일부만 수정한다 | 아니오 | 아니오 |
| DELETE | 리소스를 삭제한다 | 아니오 | 예 |
멱등은 같은 요청을 여러 번 보내도 결과가 같다는 뜻이다. AWS 문서의 설명대로 같은 POST를 여러 번 보내면 같은 리소스가 여러 개 만들어지는 부작용이 생기고, 같은 PUT을 여러 번 보내면 결과가 같다. 그래서 네트워크 오류로 재시도해야 할 때 PUT은 안전하게 다시 보낼 수 있지만 POST는 중복 생성을 조심해야 한다.
아래는 이 메서드로 사용자 리소스를 설계한 예시다.
| 요청 | 의미 |
|---|---|
| GET /users/42 | 42번 사용자 조회 |
| POST /users | 새 사용자 생성(성공 시 201) |
| PUT /users/42 | 42번 사용자 정보 전체 교체 |
| PATCH /users/42 | 42번 사용자 정보 일부 수정 |
| DELETE /users/42 | 42번 사용자 삭제 |
URL에는 동사 대신 리소스 이름을 두고 하려는 동작은 메서드가 나타낸다는 점이 포인트라고 이해했다.
상태 코드
응답의 상태 코드는 다섯 부류로 나뉜다.
| 범위 | 의미 |
|---|---|
| 1xx | 정보 응답 |
| 2xx | 성공 |
| 3xx | 리다이렉션 |
| 4xx | 클라이언트 오류 |
| 5xx | 서버 오류 |
API를 만들고 운영할 때 자주 마주치는 코드는 아래와 같다.
| 코드 | 의미 |
|---|---|
| 201 | 요청이 성공해 새 리소스가 만들어짐, 보통 POST 뒤에 보낸다 |
| 400 | 클라이언트 오류로 판단되는 잘못된 요청 |
| 401 | 이름은 unauthorized지만 의미는 인증되지 않음, 인증이 필요하다 |
| 403 | 접근 권한이 없음, 401과 달리 서버가 클라이언트의 신원을 안다 |
| 404 | 리소스를 찾을 수 없음, API에서는 엔드포인트는 맞지만 리소스가 없다는 뜻일 수도 있다 |
| 429 | 짧은 시간에 요청을 너무 많이 보냄(속도 제한) |
| 500 | 서버가 처리 방법을 모르는 상황, 일반적인 서버 오류 |
| 502 | 게이트웨이로 동작하던 서버가 유효하지 않은 응답을 받음 |
| 503 | 서버가 요청을 처리할 준비가 안 됨, 점검이나 과부하 같은 일시적 상태 |
| 504 | 게이트웨이로 동작하던 서버가 제때 응답을 받지 못함 |
502/503/504는 중간에 게이트웨이나 프록시가 있는 구조에서 나온다는 점이 눈에 띈다. 프록시와 이어 보면 이런 코드는 요청이 서버 앞단의 중간 계층에서 막혔는지 확인할 때 단서가 된다.
인증 방식
REST API는 응답을 보내기 전에 요청을 인증해야 한다. AWS 문서가 설명하는 흔한 방식은 네 가지다.
| 방식 | 설명 |
|---|---|
| HTTP 기본 인증 | 사용자 이름과 비밀번호를 base64로 인코딩해 요청 헤더에 담아 보낸다 |
| 베어러 인증 | 로그인 요청에 대한 응답으로 서버가 만든 토큰을 헤더에 담아 보낸다 |
| API 키 | 서버가 처음 온 클라이언트에게 고유한 값을 주고, 이후 요청마다 그 값으로 신원을 증명한다. 키를 전송해야 해서 네트워크에서 탈취될 수 있어 상대적으로 덜 안전하다 |
| OAuth | 비밀번호와 토큰을 결합하고, 토큰은 범위와 유효 기간을 지정해 확인할 수 있다 |
AWS의 Amazon API Gateway는 API를 만들고 게시/관리/모니터링/보호하는 완전 관리형 서비스다. IAM과 Cognito로 접근 권한을 제어하고, 같은 API의 여러 버전을 동시에 운영하며, 호출 수/지연 시간/오류율 같은 지표를 볼 수 있다고 한다.
응답의 구성
REST 원칙에 따르면 응답에는 세 가지가 들어간다. 상태 줄에는 세 자리 상태 코드가 있고 본문에는 리소스의 표현이 들어간다. 클라이언트는 요청 헤더로 XML이나 JSON 형식을 요청할 수 있고 서버는 이를 보고 적절한 형식으로 응답한다. 헤더에는 서버/인코딩/날짜/콘텐츠 유형 같은 응답의 메타데이터가 들어간다.
그 외 웹 기술과 프로토콜
HTTP 요청과 응답만으로는 부족한 상황을 위한 기술이 따로 있다.
| 기술 | 방향 | 특징 |
|---|---|---|
| HTTP/2 | 요청/응답 | 메시지를 이진 프레임에 담아 헤더를 압축하고 한 연결에서 여러 메시지를 동시에 주고받는다(멀티플렉싱). 메시지의 의미는 HTTP/1.1과 같다 |
| Fetch API | 요청/응답 | 자바스크립트에서 HTTP 요청을 보내는 API로, XMLHttpRequest를 대체했다 |
| 서버 전송 이벤트(SSE) | 서버에서 클라이언트로 단방향 | HTTP를 전송 수단으로 쓰고, 클라이언트가 EventSource로 연결을 열어 이벤트를 받는다 |
| WebSocket | 양방향 | 브라우저와 서버 사이에 양방향 대화 세션을 열어 폴링 없이 메시지를 주고받는다 |
WebSocket은 HTTP 요청/응답과 달리 한 번 연결하면 서버도 먼저 메시지를 보낼 수 있다. 시작은 HTTP 요청으로 하고, Sec-WebSocket-Key/Sec-WebSocket-Accept 같은 헤더로 서버가 연결을 WebSocket으로 업그레이드하겠다고 알리는 핸드셰이크를 거친다. MDN은 WebSocket 인터페이스가 안정적이고 브라우저와 서버 지원이 좋다고 하면서 많은 용도에서 WebTransport가 WebSocket을 대체할 것으로 예상된다고 덧붙인다. WebTransport는 단방향 스트림/순서 없는 전달/데이터그램을 지원하지만 더 복잡하고 브라우저 지원이 덜하다. 일반적인 양방향 연결이면 WebSocket으로 빠르게 시작하고, 특수한 요구가 있을 때 WebTransport를 고려한다고 이해했다.
핵심 복습
| 키워드 | 한 줄 정리 |
|---|---|
| REST | API가 따를 아키텍처 규칙, 균일한 인터페이스/무상태/계층형/캐시 가능 |
| 무상태 | 서버가 각 요청을 독립적으로 처리해 확장성이 좋음 |
| 요청 구성 | URL + 메서드 + 헤더 + 데이터 + 파라미터 |
| 메서드 | GET 조회, POST 생성/제출, PUT 전체 교체, PATCH 일부 수정, DELETE 삭제 |
| 멱등 | GET/PUT/DELETE는 여러 번 보내도 결과가 같음, POST/PATCH는 아님 |
| 상태 코드 | 2xx 성공, 3xx 이동, 4xx 클라이언트 오류, 5xx 서버 오류 |
| 401과 403 | 인증 안 됨 vs 신원은 알지만 권한 없음 |
| 인증 | 기본 인증, 베어러 토큰, API 키, OAuth |
| WebSocket | 한 번 연결해 양방향으로 메시지를 주고받는 기술 |
📍 참고 자료
확인일: 2026-10-03
