REST API 쉽게 이해하기 - HTTP 메서드와 설계 원칙 완전 정리

2 조회

REST API는 HTTP를 기반으로 자원을 URL로 표현하고 메서드로 조작하는 웹 API 설계 방식이다.

이 글은 API를 처음 다루는 개발자와 REST의 원칙을 정확히 이해하고 싶은 사람을 위해 작성되었다. 이론부터 실제 URL 설계 예시까지, REST API의 모든 것을 한 번에 정리한다.

REST API 개념

REST API란?

REST(Representational State Transfer)는 Roy Fielding이 2000년 박사 논문에서 제안한 웹 아키텍처 스타일이다. REST의 원칙을 따르는 API를 RESTful API 또는 REST API라고 한다.

Postman 2025 State of the API 보고서에 따르면, API 개발자의 89%가 REST API를 사용하고 있다. 사실상 웹 API의 표준이다.

REST의 6가지 핵심 원칙

  1. 클라이언트-서버 분리 화면(클라이언트)과 데이터·비즈니스 로직(서버)을 분리한다. 서로 독립적으로 발전할 수 있다.

  2. 무상태(Stateless) 각 요청은 독립적이어야 하며, 서버는 이전 요청을 기억하지 않는다. 인증 정보는 매 요청에 포함해야 한다.

  3. 캐시 가능(Cacheable) 응답 데이터를 클라이언트가 캐싱할 수 있어 성능을 향상시킨다.

  4. 계층형 시스템(Layered System) 클라이언트는 중간 서버(로드밸런서, 캐시 서버) 존재 여부를 알 필요 없다.

  5. 인터페이스 일관성(Uniform Interface) 자원 식별(URL), 표현을 통한 조작, 자기 서술적 메시지 등 일관된 규칙을 따른다.

  6. Code On Demand (선택적) 서버가 실행 가능한 코드를 클라이언트에 전달할 수 있다. (거의 사용 안 함)

HTTP 메서드와 CRUD 매핑

REST API에서 자원에 대한 행위는 HTTP 메서드로 표현한다:

HTTP 메서드역할CRUD예시
GET조회ReadGET /users (목록), GET /users/1 (단건)
POST생성CreatePOST /users (신규 생성)
PUT전체 수정UpdatePUT /users/1 (전체 교체)
PATCH부분 수정UpdatePATCH /users/1 (일부 변경)
DELETE삭제DeleteDELETE /users/1

RESTful URL 설계 원칙

좋은 REST URL 설계:

GET    /posts           # 포스트 목록 조회
GET    /posts/123       # ID 123 포스트 조회
POST   /posts           # 포스트 생성
PUT    /posts/123       # ID 123 포스트 전체 수정
PATCH  /posts/123       # ID 123 포스트 부분 수정
DELETE /posts/123       # ID 123 포스트 삭제
GET    /posts/123/comments  # 포스트 123의 댓글 목록

피해야 할 URL 설계:

GET  /getPost          # ❌ 동사 사용 금지 (메서드가 이미 행위 표현)
POST /createUser       # ❌ URL에 행위 포함 금지
GET  /delete_post/123  # ❌ 삭제는 DELETE 메서드로

API 응답 형식 (JSON)

REST API는 주로 JSON 형식으로 데이터를 주고받는다:

// 성공 응답
{
  "success": true,
  "data": {
    "id": 123,
    "title": "REST API 가이드",
    "author": "홍길동"
  }
}

// 에러 응답
{
  "success": false,
  "error": "게시글을 찾을 수 없습니다.",
  "code": 404
}

HTTP 상태 코드

코드의미설명
200 OK성공조회, 수정 성공
201 Created생성 성공POST 요청 성공
400 Bad Request잘못된 요청파라미터 오류
401 Unauthorized인증 필요로그인 필요
403 Forbidden권한 없음접근 거부
404 Not Found찾을 수 없음자원 없음
500 Internal Server Error서버 오류서버 내부 오류

REST API vs GraphQL 비교

REST API vs GraphQL

구분REST APIGraphQL
데이터 요청URL별 고정 응답원하는 필드만 요청
엔드포인트자원별 여러 URL단일 /graphql 엔드포인트
Over-fetching발생 가능없음
Under-fetchingN+1 문제없음
러닝 커브낮음높음
사용 사례대부분의 웹 APIFacebook, GitHub, Shopify

자주 묻는 질문 (FAQ)

Q1. RESTful API와 REST API는 같은 말인가요? A. 사실상 같은 의미로 사용된다. REST는 아키텍처 스타일이고, RESTful은 REST의 원칙을 잘 따른다는 형용사적 표현이다. 완전한 REST 원칙을 따르지 않더라도 REST API라고 부르는 경우가 많다.

Q2. PUT과 PATCH의 차이는 무엇인가요? A. PUT은 자원의 전체를 교체하는 것이고, PATCH는 일부만 수정하는 것이다. 예를 들어 사용자 이름만 변경하려면 PATCH를 사용하고, 사용자 전체 정보를 새로 교체하려면 PUT을 사용한다.

Q3. REST API와 SOAP API의 차이는? A. SOAP는 XML 기반의 엄격한 프로토콜로, 보안(WS-Security)과 트랜잭션을 지원하여 금융·의료 엔터프라이즈 시스템에서 사용한다. REST는 HTTP 기반으로 가볍고 유연하여 대부분의 웹·모바일 서비스에 사용된다.

Q4. API 버전 관리는 어떻게 하나요? A. 주로 URL에 버전을 포함하는 방법(/api/v1/posts, /api/v2/posts)을 사용한다. 또는 HTTP 헤더에 버전을 포함하거나(Accept: application/vnd.api+json;version=2), 쿼리 파라미터를 사용하기도 한다.

Q5. REST API를 테스트하는 도구는 무엇이 있나요? A. Postman, Insomnia, Thunder Client(VS Code 확장)가 대표적이다. curl 명령어로도 테스트할 수 있다. 개발 단계에서는 Swagger(OpenAPI)를 사용하면 API 문서와 테스트를 함께 관리할 수 있다.

공유