REST API 이해하기 - 웹 개발 입문자가 꼭 알아야 할 핵심 원리 정리
GET, POST, PUT, DELETE부터 상태 코드, 인증까지 REST API의 모든 것을 실전 예제와 함께 쉽게 풀어드립니다
웹 서비스를 만들거나 외부 데이터를 가져오려고 문서를 열었는데, 온통 GET, POST, endpoint 같은 용어뿐이라 막막했던 경험이 있으실 겁니다. REST API 이해하기는 웹 개발을 시작하는 분이라면 가장 먼저 넘어야 할 산입니다. 한번 개념을 잡으면 어떤 서비스의 API 문서든 자신 있게 읽을 수 있습니다.
REST API란 무엇인가
REST는 Representational State Transfer의 약자로, 2000년 로이 필딩(Roy Fielding)이 박사 논문에서 처음 제안한 아키텍처 스타일입니다. 쉽게 말해, 클라이언트와 서버가 데이터를 주고받는 방식에 대한 약속입니다.
API(Application Programming Interface)는 프로그램끼리 소통하는 창구입니다. 식당에 비유하면 메뉴판이 API이고, 주문 방식이 REST라고 생각하면 됩니다. REST 방식을 따르는 API를 REST API 또는 RESTful API라고 부릅니다.
REST API가 널리 쓰이는 이유
- 단순함 - HTTP 프로토콜을 그대로 활용하므로 별도 프로토콜을 배울 필요가 없습니다
- 확장성 - 클라이언트와 서버가 독립적으로 발전할 수 있습니다
- 범용성 - 웹, 모바일, IoT 등 어떤 플랫폼에서든 호출할 수 있습니다
- 생태계 - 전 세계 웹 서비스의 약 83%가 REST 기반 API를 제공합니다(Postman 2023 API 현황 보고서 기준)
REST API의 6가지 설계 원칙
REST API 이해하기 위해서는 핵심 설계 원칙부터 알아야 합니다. 로이 필딩이 정의한 6가지 제약 조건을 살펴보겠습니다.
| 원칙 | 설명 | 실전 예시 |
|---|---|---|
| 클라이언트-서버 분리 | UI와 데이터 저장을 분리 | 프론트엔드(React)와 백엔드(Node.js)를 각각 개발 |
| 무상태성(Stateless) | 각 요청은 독립적, 서버가 상태를 저장하지 않음 | 매 요청마다 인증 토큰을 포함해서 전송 |
| 캐시 가능(Cacheable) | 응답 데이터에 캐시 여부를 명시 | Cache-Control 헤더로 브라우저 캐시 제어 |
| 일관된 인터페이스 | URL과 메서드 사용 규칙 통일 | /users/123에 GET 요청 = 123번 사용자 조회 |
| 계층화 시스템 | 중간 서버(로드밸런서, 프록시) 삽입 가능 | CDN을 중간에 두어 응답 속도 향상 |
| Code on Demand(선택) | 서버가 실행 가능한 코드를 전송 가능 | JavaScript 파일을 서버에서 내려받아 실행 |
REST API의 핵심은 "자원(Resource)을 URL로 표현하고, 행위(Action)를 HTTP 메서드로 구분한다"는 것입니다. 이 한 문장만 기억해도 대부분의 API 문서를 읽을 수 있습니다.
HTTP 메서드와 상태 코드 완전 정복
REST API에서 가장 자주 쓰이는 HTTP 메서드는 4가지입니다. CRUD(Create, Read, Update, Delete) 작업과 1:1로 대응됩니다.
주요 HTTP 메서드
- GET - 데이터 조회. 서버의 데이터를 변경하지 않습니다. 예: GET /api/posts/42
- POST - 데이터 생성. 새로운 리소스를 만듭니다. 예: POST /api/posts
- PUT - 데이터 전체 수정. 기존 리소스를 완전히 교체합니다. 예: PUT /api/posts/42
- PATCH - 데이터 부분 수정. 특정 필드만 변경합니다. 예: PATCH /api/posts/42
- DELETE - 데이터 삭제. 리소스를 제거합니다. 예: DELETE /api/posts/42
반드시 알아야 할 HTTP 상태 코드
서버는 요청을 처리한 후 숫자 코드로 결과를 알려줍니다. 개발 중 가장 자주 마주치는 코드를 정리했습니다.
| 코드 | 의미 | 설명 |
|---|---|---|
| 200 | OK | 요청 성공 |
| 201 | Created | 리소스 생성 성공 (POST 응답) |
| 204 | No Content | 성공했지만 응답 본문 없음 (DELETE 응답) |
| 400 | Bad Request | 잘못된 요청 형식 |
| 401 | Unauthorized | 인증 필요 |
| 403 | Forbidden | 권한 없음 |
| 404 | Not Found | 리소스가 존재하지 않음 |
| 429 | Too Many Requests | 요청 횟수 초과 (Rate Limit) |
| 500 | Internal Server Error | 서버 내부 오류 |
REST API 실전 요청 구조 분석
실제 REST API 요청이 어떻게 생겼는지 살펴보겠습니다. 아래는 사용자 정보를 조회하는 전형적인 GET 요청의 구조입니다.
요청(Request) 구성 요소
1) 엔드포인트(Endpoint) - 요청을 보내는 URL입니다.
예시: https://api.example.com/v1/users/42
- Base URL: https://api.example.com
- 버전: /v1
- 리소스: /users
- 식별자: /42
2) 헤더(Headers) - 요청의 메타 정보를 담습니다.
Content-Type: application/json은 "본문이 JSON 형식"이라는 뜻이고, Authorization: Bearer abc123은 인증 토큰을 전달합니다.
3) 바디(Body) - POST, PUT, PATCH 요청에서 전송할 데이터를 담습니다. GET과 DELETE에는 보통 본문이 없습니다.
응답(Response) 예시
서버가 돌려주는 응답은 대부분 JSON 형식입니다. 상태 코드와 함께 요청한 데이터가 포함됩니다. 예를 들어 사용자 조회 응답에는 id, name, email 같은 필드가 들어오고, 목록 조회라면 배열 형태로 여러 건이 반환됩니다.
API를 테스트할 때 자신의 네트워크 환경을 확인해야 할 때가 있습니다. 사내 API가 IP 기반 접근 제한을 걸어둔 경우, 내 IP 주소 확인 도구로 현재 IP를 빠르게 파악하면 화이트리스트 등록이 훨씬 수월합니다.
REST API 인증과 보안 기초
공개 API가 아닌 이상, 대부분의 REST API는 인증(Authentication) 절차를 요구합니다. 누가 요청을 보냈는지 서버가 확인해야 하기 때문입니다.
주요 인증 방식
- API Key - 서버가 발급한 고유 키를 헤더나 쿼리 파라미터로 전달합니다. 가장 단순한 방식입니다
- Bearer Token (JWT) - 로그인 후 발급받은 토큰을 Authorization 헤더에 포함합니다. 현재 가장 널리 쓰이는 방식입니다
- OAuth 2.0 - 구글, 카카오 로그인처럼 제3자 인증을 위임하는 방식입니다. 소셜 로그인에 주로 활용됩니다
- Basic Auth - 아이디와 비밀번호를 Base64로 인코딩하여 전송합니다. 보안이 취약해 운영 환경에서는 권장하지 않습니다
API Key나 토큰은 사실상 비밀번호와 같은 역할을 합니다. 영문 대소문자, 숫자, 특수문자를 조합한 충분히 긴 키를 사용해야 안전합니다. 직접 키를 생성해야 하는 상황이라면 비밀번호 생성기를 활용해 무작위 문자열을 만드는 것도 방법입니다.
REST API 설계 시 자주 하는 실수 5가지
REST API 이해하기만큼 중요한 것이 올바르게 설계하는 것입니다. 실무에서 흔히 보이는 실수를 정리했습니다.
1. URL에 동사를 넣는 실수
잘못된 예: /getUsers, /createPost, /deleteUser/42
올바른 예: GET /users, POST /posts, DELETE /users/42
행위는 HTTP 메서드가 표현합니다. URL에는 명사(리소스)만 넣으세요.
2. 일관성 없는 네이밍
/user-list, /UserProfile, /get_orders처럼 표기법이 섞이면 사용하는 쪽에서 혼란스럽습니다. 케밥 케이스(kebab-case)로 통일하는 것이 일반적입니다.
3. 적절하지 않은 상태 코드 반환
모든 응답에 200을 반환하고 본문에 "error: true"를 넣는 API가 의외로 많습니다. 상태 코드를 정확히 사용해야 클라이언트에서 에러 처리가 수월합니다.
4. 버전 관리를 하지 않는 실수
API 구조가 바뀌면 기존 사용자의 앱이 깨집니다. /v1/users, /v2/users처럼 URL에 버전을 포함하거나, 헤더로 버전을 관리하세요.
5. 페이지네이션 미적용
데이터가 10만 건인데 한 번에 전부 반환하면 서버와 클라이언트 모두 부담됩니다. offset/limit 또는 cursor 기반 페이지네이션은 필수입니다.
REST API는 웹 개발의 공용어입니다. 프론트엔드 개발자도, 백엔드 개발자도, 기획자도 알아야 하는 기본 소양이 되었습니다. 오늘 정리한 내용을 바탕으로 Postman이나 curl을 설치해서 공개 API 하나를 직접 호출해보세요. 실제로 요청을 보내고 응답을 확인하는 순간, 글로 읽었던 개념이 머릿속에 확실히 자리잡게 됩니다.
