RESTful API 완벽 가이드

RESTful API 완벽 가이드 — 백엔드 개발자가 꼭 알아야 할 핵심 정리

이 글은 RESTful API의 개념부터 설계 원칙, 실제 예시, 그리고 자주 하는 실수까지 모두 정리한 공부글입니다.

1. REST란 무엇인가?

REST (Representational State Transfer) 는 웹 기반 시스템에서 리소스를 효율적으로 관리하고 전달하기 위한 아키텍처 스타일입니다.

즉, "자원을 URI로 식별하고, 그 자원에 대한 상태를 HTTP 메서드로 표현하며, 서버와 클라이언트가 느슨하게 연결된 구조로 통신하는 방식"입니다.

2. REST의 핵심 구성 요소

구성 요소	설명	예시
Resource (자원)	서버가 제공하는 데이터나 기능	/users, /posts/1
URI (자원의 식별자)	각 자원을 식별하는 고유 주소	https://api.example.com/users/1
HTTP Method (행위)	자원에 대해 수행할 동작	GET, POST, PUT, DELETE
Representation (표현)	자원의 실제 데이터 형태	JSON, XML, HTML 등

3. REST의 6가지 제약 조건 (RESTful의 기준)

제약 조건	설명
1. Client-Server	클라이언트와 서버의 역할을 명확히 분리해야 함. (UI ↔ 데이터)
2. Stateless (무상태성)	각 요청은 독립적이어야 하며, 서버는 클라이언트 상태를 저장하지 않음.
3. Cacheable (캐시 가능)	서버 응답은 캐싱이 가능해야 함. 성능 향상과 네트워크 부하 감소 목적.
4. Uniform Interface	일관된 인터페이스로 설계되어야 함. (URI 규칙, HTTP method 일관성 등)
5. Layered System	서버는 여러 계층으로 나눠질 수 있으며, 클라이언트는 그 구조를 몰라도 됨.
6. Code on Demand (Optional)	서버가 클라이언트에 코드를 전송해 실행시킬 수 있음 (자바스크립트 등).

4. RESTful API란?

REST의 원칙을 준수하며 설계된 API를 RESTful API라고 합니다.

즉,

• 자원(Resource)을 명확하게 URI로 표현하고,
• 행위(Action)는 HTTP 메서드로 구분하며,
• Stateless한 통신을 유지하는 API입니다.

5. HTTP 메서드와 CRUD 매핑

HTTP Method	CRUD	설명	예시
GET	Read	자원 조회	/users, /users/1
POST	Create	새 자원 생성	/users
PUT	Update	자원 전체 수정	/users/1
PATCH	Update	자원 일부 수정	/users/1
DELETE	Delete	자원 삭제	/users/1

PUT은 전체 교체, PATCH는 부분 수정에 사용합니다.

6. RESTful URI 설계 원칙

올바른 예시

• 리소스는 명사로 표현할 것

  • /users/1/posts
  • /getUserPosts (잘못된 예시)

• 소문자와 하이픈(-) 사용

  • /user-comments
  • /UserComments (잘못된 예시)

• 계층 관계는 URI로 표현

  • /users/1/orders/2

• 파일 확장자 사용 금지

  • /users
  • /users.json (잘못된 예시)

• 버전은 명시적으로 관리

  • /api/v1/users

7. RESTful 응답 구조 예시

성공 응답 (200 OK)

{
  "status": 200,
  "message": "User retrieved successfully",
  "data": {
    "id": 1,
    "name": "austin",
    "email": "austin@example.com"
  }
}

에러 응답 (404 Not Found)

{
  "status": 404,
  "error": "User not found"
}

일관된 응답 포맷을 유지하는 것이 매우 중요합니다.
(예: status, message, data 구조)

8. RESTful API 예시 시나리오

회원 관리 API

기능	메서드	URI	설명
회원 목록 조회	GET	/users	모든 회원 조회
회원 상세 조회	GET	/users/{id}	특정 회원 조회
회원 등록	POST	/users	회원 추가
회원 정보 수정	PUT	/users/{id}	회원 정보 전체 수정
회원 탈퇴	DELETE	/users/{id}	회원 삭제

9. RESTful 하지 않은 예시 (Anti-Pattern)

잘못된 예시	올바른 예시	이유
/getUsers	/users	동작(verb)이 아닌 자원(noun)으로 표현해야 함
/createUser	/users (POST)	HTTP 메서드로 행위를 표현해야 함
/updateUser?id=1	/users/1 (PUT)	리소스 ID는 URI 경로로 표현
/deleteUser/1	/users/1 (DELETE)	행위는 DELETE로 표현

10. RESTful API의 장점과 한계

장점

• 구조가 단순하고 직관적
• 클라이언트-서버의 독립성
• 확장성 및 유지보수 용이
• HTTP 표준 기반으로 폭넓은 호환성

한계

• 복잡한 트랜잭션 처리에는 부적합
• 다수의 요청이 필요한 경우 비효율적
• 실시간 통신에는 부적합 (→ WebSocket 권장)

11. REST vs 다른 아키텍처

구분	REST	GraphQL	gRPC
통신 방식	HTTP	HTTP	HTTP/2
데이터 전송	JSON	JSON	Protocol Buffers
요청 단위	여러 엔드포인트	단일 엔드포인트	서비스 메서드 기반
주요 장점	단순하고 표준화	필요한 데이터만 요청 가능	고성능, 이진 데이터
사용 예시	웹/모바일 API	프론트엔드 최적화	마이크로서비스 간 통신

12. RESTful API 설계 시 자주 하는 실수

1. HTTP 상태코드를 잘못 사용

• 200 OK만 사용하는 것은 좋지 않음.
• 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error 등 명확히 구분 필요.

2. URI에 동사 포함

• GET /getUserList → ❌

3. 에러 메시지 비일관성

• 클라이언트가 일관된 방식으로 에러를 처리할 수 없게 됨.

4. Stateless 위반

• 세션 기반 인증을 사용하면 REST 원칙 위반 (→ JWT 권장)

13. RESTful API 설계 체크리스트

• URI는 명사 기반으로 작성했는가?
• HTTP 메서드를 적절히 사용했는가?
• 상태 코드를 올바르게 반환하는가?
• JSON 응답 포맷이 일관적인가?
• 버전 관리(/v1, /v2)를 하고 있는가?
• 예외 및 에러 처리가 명확한가?
• 캐시, 보안(HTTPS), 인증(JWT)을 고려했는가?

14. 마무리 — "RESTful하게" 설계한다는 것

RESTful API는 단순히 GET/POST를 사용하는 것이 아닙니다.
자원의 구조, 행위의 표현, 일관성, 확장성을 고려한 하나의 규칙입니다.

결국 좋은 API는 "개발자가 직관적으로 이해할 수 있는 API"입니다.