REST API

기본 정보

• 명칭: REST API
• 영문명: Representational State Transfer API
• 분류: 웹 API 아키텍처 스타일
• 최초 제안: 2000년 (Roy Fielding)
• 주요 용도: 클라이언트와 서버 간 데이터 통신
• 관련 주제: #RESTAPI #API #HTTP #JSON #백엔드

개요

REST API는 HTTP 프로토콜을 기반으로 리소스(Resource)를 URL로 표현하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 이용해 데이터를 처리하는 API 설계 방식이다.

현재 웹 서비스, 모바일 앱, SaaS, ERP, AI 서비스 등 대부분의 시스템에서 표준적인 API 방식으로 사용되고 있다.

REST API는 프론트엔드와 백엔드를 분리하여 개발할 수 있도록 해주며, JSON 형식을 이용한 데이터 교환이 일반적이다.

REST API 구조

Client

↓

HTTP Request

↓

REST API

↓

Business Logic

↓

Database

↓

JSON Response

↓

Client

REST의 핵심 개념

REST는 리소스(Resource)를 중심으로 설계한다.

예시

/users

/products

/orders

/posts

/comments

URL은 동사보다 명사를 사용하는 것이 일반적이다.

HTTP Method

GET

회원 조회

GET /api/users/1

응답

{
  "id": 1,
  "name": "구름"
}

POST

회원 생성

POST /api/users

Body

{
  "name": "홍길동"
}

PUT

회원 전체 수정

PUT /api/users/1

PATCH

회원 일부 수정

PATCH /api/users/1

DELETE

회원 삭제

DELETE /api/users/1

URL 설계 예시

좋은 예

/users

/users/1

/users/1/orders

/products/10

좋지 않은 예

/getUser

/deleteUser

/updateMember

REST에서는 URL보다 HTTP Method로 동작을 구분한다.

Request 예시

GET /api/products

Host: example.com

Authorization: Bearer token

Response 예시

{
  "success": true,
  "message": "조회 성공",
  "data": [
    {
      "id": 1,
      "name": "노트북"
    }
  ]
}

상태 코드(Status Code)

인증 방식

대표 인증 방법

• API Key
• Session
• JWT
• OAuth 2.0

JWT 예시

Authorization:

Bearer eyJhb...

페이징

/api/products?page=1&size=20

대량 데이터를 효율적으로 조회하기 위해 사용한다.

필터링

/api/products?category=pc

정렬

/api/products?sort=price

검색

/api/products?keyword=laptop

API 버전 관리

/api/v1/users

/api/v2/users

기존 클라이언트와의 호환성을 유지하기 위해 사용한다.

REST 제약 조건

REST 아키텍처는 일반적으로 다음 원칙을 따른다.

• Client-Server 구조
• Stateless(무상태)
• Cache 가능
• Uniform Interface
• Layered System
• Code on Demand(선택)

REST API 장점

• 구조가 단순함
• HTTP 표준 활용
• 플랫폼 독립적
• 프론트엔드와 백엔드 분리 가능
• 확장성이 높음
• 유지보수가 용이

REST API 단점

• 실시간 통신에는 한계
• 과도한 요청 발생 가능
• 버전 관리 필요
• 복잡한 조회에서는 여러 API 호출이 필요할 수 있음

GraphQL과 비교

주요 활용 분야

• 모바일 앱
• 쇼핑몰
• ERP
• SaaS
• 관리자 시스템
• 커뮤니티
• AI 서비스
• 클라우드 서비스

실무 메모

실무에서는 다음과 같은 방식이 권장된다.

• URL은 명사형으로 작성
• HTTP Method를 올바르게 사용
• JSON 응답 형식 통일
• JWT 기반 인증 적용
• HTTPS 사용
• Pagination 지원
• Rate Limit 적용
• OpenAPI(Swagger) 문서 제공
• 입력값 검증
• 예외 처리와 로그 기록 표준화

REST API와 함께 사용하는 기술

• API
• HTTP
• HTTPS
• JSON
• JWT
• OAuth
• Swagger
• OpenAPI
• React
• Flutter

대표 개발 도구

• Postman
• Swagger UI
• Bruno
• Insomnia
• curl
• OpenAPI Generator

관련 문서

• API
• JSON
• HTTP
• HTTPS
• JWT
• OAuth
• Swagger
• OpenAPI
• GraphQL
• 백엔드

출처

• RESTfulAPI.net
• Roy Fielding REST Dissertation
• MDN Web Docs - HTTP