개발 기초

REST API 초보자를 위한 완벽 가이드: 개념부터 실전까지

November 23, 2025 8분 읽기 0
REST API 초보자 가이드 HTTP 메서드 GET POST PUT DELETE 설명 다이어그램 클라이언트 서버 통신 구조

웹 개발을 시작하면서 REST API라는 용어를 자주 접하게 되셨나요? API 문서를 보면서 GET, POST, PUT, DELETE가 무엇인지 헷갈리셨나요? 이 가이드는 REST API의 개념부터 실제 사용법까지 초보자도 쉽게 이해할 수 있도록 상세히 설명합니다.

REST API란 무엇인가?

REST API는 두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스입니다 Amazon Web Services. REST는 Representational State Transfer의 약자로, 웹 서비스 설계를 위한 아키텍처 스타일입니다.

쉽게 말해, REST API는 웹 애플리케이션들이 서로 대화하는 방법을 정의한 규칙입니다. 레스토랑에서 메뉴판을 보고 주문하는 것처럼, 클라이언트는 REST API를 통해 서버에 요청을 보내고 필요한 데이터를 받아옵니다.

REST API의 핵심 구성 요소

REST API는 세 가지 주요 요소로 구성됩니다:

1. 자원(Resource) 데이터나 서비스를 의미하며, 고유한 URI로 식별됩니다. 예를 들어 https://api.example.com/users/123에서 사용자 정보가 자원입니다.

2. 행위(HTTP Method) 자원에 대해 수행할 작업을 나타냅니다. GET, POST, PUT, DELETE 등의 HTTP 메서드로 표현됩니다.

3. 표현(Representation) 클라이언트가 서버로 요청을 보냈을 때 서버가 응답으로 보내주는 자원의 상태를 의미하며, JSON은 가장 널리 사용되는 파일 형식입니다 Red Hat.

REST API의 주요 특징

1. 무상태성(Stateless)

서버는 클라이언트의 이전 요청을 기억하지 않습니다. 각 요청은 독립적이며 필요한 모든 정보를 포함해야 합니다. 이는 서버의 부담을 줄이고 확장성을 높입니다.

2. 클라이언트-서버 구조

클라이언트와 서버가 독립적으로 개발되고 진화할 수 있어, 프론트엔드와 백엔드를 분리하여 개발할 수 있습니다.

3. 캐시 가능(Cacheable)

HTTP 프로토콜의 캐싱 기능을 그대로 활용할 수 있어 응답 속도를 향상시킬 수 있습니다.

4. 계층화 시스템

API 서버 앞에 보안, 로드밸런싱 등을 처리하는 계층을 추가하여 구조상 유연성을 제공합니다.

HTTP 메서드 완벽 정리

REST API에서 가장 중요한 HTTP 메서드 4가지를 데이터베이스의 CRUD 작업과 연결하여 이해해봅시다.

GET – 조회(Read)

서버에서 데이터를 가져올 때 사용합니다. 데이터를 변경하지 않는 안전한 메서드입니다.

예제:

GET /users/123
응답: 사용자 123번의 정보를 반환

특징:

  • URL에 쿼리 파라미터로 데이터 전달
  • 브라우저 히스토리에 남음
  • 북마크 가능
  • 캐싱 가능

POST – 생성(Create)

서버에 새로운 데이터를 생성할 때 사용합니다. 요청 본문(body)에 데이터를 담아 전송합니다.

예제:

POST /users
Content-Type: application/json
{
  "name": "홍길동",
  "email": "hong@example.com"
}
응답: 새로 생성된 사용자 정보 반환

특징:

  • 요청 본문에 데이터 포함
  • URL에 데이터가 노출되지 않음
  • 캐싱되지 않음
  • 여러 번 실행 시 매번 새로운 리소스 생성

PUT – 전체 수정(Update)

기존 리소스의 전체를 갱신할 때 사용하며, 존재하지 않는 경우 새로운 자원을 생성할 수 있습니다 Velog.

예제:

PUT /users/123
Content-Type: application/json
{
  "name": "홍길동",
  "email": "newhong@example.com",
  "age": 30
}
응답: 수정된 사용자 정보 전체 반환

DELETE – 삭제(Delete)

서버의 리소스를 삭제할 때 사용합니다.

예제:

DELETE /users/123
응답: 204 No Content (성공)

PATCH – 부분 수정

PUT과 달리 리소스의 일부만 수정할 때 사용합니다.

예제:

PATCH /users/123
Content-Type: application/json
{
  "email": "newhong@example.com"
}
응답: 이메일만 수정된 사용자 정보 반환

REST API URI 설계 원칙

좋은 REST API는 직관적이고 이해하기 쉬운 URI를 사용합니다.

1. 명사를 사용하라

URI는 자원을 나타내므로 동사가 아닌 명사를 사용합니다.

좋은 예:

  • GET /users – 사용자 목록 조회
  • POST /users – 새 사용자 생성
  • DELETE /users/123 – 사용자 삭제

나쁜 예:

  • GET /getUsers
  • POST /createUser
  • DELETE /deleteUser/123

2. 복수형 명사 사용

컬렉션을 나타낼 때는 복수형 명사를 사용합니다.

GET /users - 사용자 목록
GET /users/123 - 특정 사용자
GET /users/123/orders - 특정 사용자의 주문 목록

3. 계층 구조 표현

슬래시(/)로 리소스 간의 계층 관계를 표현합니다.

/users/123/orders/456
→ 사용자 123번의 주문 456번

4. 소문자 사용

URI 경로에는 소문자를 사용하며, RFC 3986은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정합니다

5. 하이픈(-) 사용, 언더스코어(_) 지양

가독성을 위해 하이픈을 사용하고 언더스코어는 피합니다.

좋은 예: /user-orders
나쁜 예: /user_orders

6. 파일 확장자 미포함

URI에 파일 확장자를 포함하지 않고, Content-Type 헤더를 사용합니다.

좋은 예: GET /users/123
나쁜 예: GET /users/123.json

REST API 실전 예제

실제 전자상거래 시스템에서 REST API를 어떻게 사용하는지 살펴봅시다.

상품 관리 API

# 모든 상품 조회
GET /products
응답: 상품 목록 (JSON 배열)

# 특정 상품 조회
GET /products/101
응답: 상품 101의 상세 정보

# 카테고리별 상품 검색
GET /products?category=electronics&sort=price
응답: 전자제품 카테고리의 상품을 가격순으로 정렬

# 새 상품 등록
POST /products
Body: { "name": "노트북", "price": 1500000, "category": "electronics" }
응답: 201 Created, 생성된 상품 정보

# 상품 정보 수정
PUT /products/101
Body: { "name": "노트북 Pro", "price": 2000000, "category": "electronics" }
응답: 200 OK, 수정된 상품 정보

# 상품 삭제
DELETE /products/101
응답: 204 No Content

주문 관리 API

# 사용자의 주문 목록 조회
GET /users/123/orders
응답: 사용자 123의 주문 목록

# 새 주문 생성
POST /users/123/orders
Body: { "productId": 101, "quantity": 2 }
응답: 201 Created, 생성된 주문 정보

# 주문 상태 변경
PATCH /orders/456
Body: { "status": "shipped" }
응답: 200 OK, 업데이트된 주문 정보

HTTP 상태 코드 이해하기

REST API의 응답에는 작업 결과를 나타내는 HTTP 상태 코드가 포함됩니다.

2xx – 성공

  • 200 OK: 요청이 성공적으로 처리됨
  • 201 Created: 새 리소스가 성공적으로 생성됨 (POST)
  • 204 No Content: 요청은 성공했으나 응답 본문이 없음 (DELETE)

3xx – 리다이렉션

  • 301 Moved Permanently: 리소스가 영구적으로 이동함
  • 304 Not Modified: 캐시된 버전을 사용할 수 있음

4xx – 클라이언트 오류

  • 400 Bad Request: 잘못된 요청
  • 401 Unauthorized: 인증 필요
  • 403 Forbidden: 권한 없음
  • 404 Not Found: 리소스를 찾을 수 없음
  • 409 Conflict: 요청이 현재 서버 상태와 충돌

5xx – 서버 오류

  • 500 Internal Server Error: 서버 내부 오류
  • 503 Service Unavailable: 서비스 이용 불가 (과부하, 유지보수)

REST API의 장점

1. 학습 곡선이 낮음

HTTP 메서드와 URL과 같은 친숙한 개념을 활용하여 개발자가 쉽게 배우고 이해할 수 있습니다 ApiDog.

2. 플랫폼 독립성

HTTP 표준만 따르면 어떤 프로그래밍 언어나 플랫폼에서도 사용 가능합니다.

3. 확장성

무상태성 덕분에 서버를 쉽게 확장할 수 있습니다.

4. 캐싱 활용

HTTP의 캐싱 메커니즘을 활용하여 성능을 향상시킬 수 있습니다.

5. 유지보수 용이성

명확한 구조와 표준화된 방식으로 코드 유지보수가 쉽습니다.

REST API 사용 시 주의사항

1. 보안

  • HTTPS를 사용하여 데이터 암호화
  • API 키나 OAuth 토큰으로 인증 구현
  • 속도 제한(Rate Limiting)으로 남용 방지

2. 버전 관리

API 변경 시 기존 사용자에게 영향을 주지 않도록 버전 관리가 필요합니다.

https://api.example.com/v1/users
https://api.example.com/v2/users

3. 에러 처리

명확하고 유익한 오류 메시지를 제공하여 사용자가 문제를 쉽게 파악할 수 있도록 합니다.

json

{
  "error": "USER_NOT_FOUND",
  "message": "해당 ID의 사용자를 찾을 수 없습니다.",
  "statusCode": 404
}

4. API 문서화

Swagger나 Postman 같은 도구를 사용하여 API 문서를 작성하고 유지관리합니다.

REST API 테스트 방법

1. 브라우저

GET 요청은 브라우저 주소창에 URL을 입력하여 간단히 테스트할 수 있습니다.

2. cURL 명령어

터미널에서 cURL을 사용하여 모든 HTTP 메서드를 테스트할 수 있습니다.

bash

# GET 요청
curl https://api.example.com/users

# POST 요청
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"홍길동","email":"hong@example.com"}'

# DELETE 요청
curl -X DELETE https://api.example.com/users/123

3. Postman

GUI 기반의 강력한 API 테스트 도구로, 요청 저장, 자동화 테스트 등 다양한 기능을 제공합니다.

4. 프로그래밍 언어

JavaScript, Python 등의 언어로 HTTP 라이브러리를 사용하여 API를 호출할 수 있습니다.

JavaScript (fetch API):

javascript

// GET 요청
fetch('https://api.example.com/users/123')
  .then(response => response.json())
  .then(data => console.log(data));

// POST 요청
fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '홍길동',
    email: 'hong@example.com'
  })
})
.then(response => response.json())
.then(data => console.log(data));

RESTful API란?

RESTful API는 REST 아키텍처 스타일을 충실히 따르는 API를 의미하며, REST 원칙을 지키는 정도가 높을수록 RESTful하다고 평가됩니다 Devpro.

RESTful API가 되기 위한 조건:

  • URI는 명사로 자원을 표현
  • 자원에 대한 행위는 HTTP 메서드로 표현
  • 슬래시(/)로 계층 관계 표현
  • URI 마지막에 슬래시 미포함
  • 하이픈(-)으로 가독성 향상
  • 소문자 사용
  • 파일 확장자 미포함

실전 활용 사례

소셜 미디어 플랫폼

  • 게시물 작성, 수정, 삭제
  • 댓글 관리
  • 좋아요/팔로우 기능
  • 사용자 프로필 조회

전자상거래

  • 상품 검색 및 조회
  • 장바구니 관리
  • 주문 처리
  • 결제 연동

모바일 앱 백엔드

  • 사용자 인증
  • 데이터 동기화
  • 푸시 알림
  • 위치 기반 서비스

IoT 디바이스 제어

  • 센서 데이터 수집
  • 디바이스 상태 모니터링
  • 원격 제어 명령 전송

결론

REST API는 현대 웹 개발의 핵심 기술입니다. HTTP 프로토콜을 기반으로 하여 배우기 쉽고, 플랫폼 독립적이며, 확장성이 뛰어납니다. 이 가이드에서 다룬 기본 개념과 설계 원칙을 이해하면, 효율적이고 유지보수하기 쉬운 API를 만들 수 있습니다.

REST API를 처음 접하는 개발자라면:

  1. GET, POST, PUT, DELETE 메서드의 차이를 명확히 이해하기
  2. URI 설계 원칙을 준수하여 직관적인 엔드포인트 만들기
  3. HTTP 상태 코드를 적절히 활용하기
  4. 실제 프로젝트에 적용하며 경험 쌓기

이제 여러분도 REST API를 활용하여 강력하고 확장 가능한 웹 서비스를 구축할 수 있습니다. 작은 프로젝트부터 시작하여 점차 복잡한 시스템으로 확장해 나가세요!

관련 글

주크박스의 두뇌: 핀 200개로 구현된 기계식 메모리의 비밀
개발 기초

주크박스의 두뇌: 핀 200개로 구현된 기계식 메모리의 비밀

2025.12.30
개발 기초

RAM과 ROM, DDR과 GDDR: 컴퓨터 메모리의 모든 것

2025.12.13
CDN이란? 콘텐츠 전송 네트워크 완벽 가이드 | 2025년 주요 CDN 서비스 비교
개발 기초

CDN이란? 콘텐츠 전송 네트워크 완벽 가이드 | 2025년 주요 CDN 서비스 비교

2025.11.26