REST API 방식이란? 구성 요소 및 장단점, 사용예제까지

REST API(Representational State Transfer Application Programming Interface)는 클라이언트와 서버 간에 HTTP 프로토콜을 기반으로 데이터를 주고받는 방식입니다. REST 아키텍처 스타일을 따르는 API를 의미하며, 웹 애플리케이션 개발에서 가장 널리 사용되는 방식 중 하나입니다.

---

1. REST API의 주요 원칙

REST는 다음과 같은 원칙을 따릅니다.

✅ 클라이언트-서버 구조 (Client-Server Architecture)
✔️ 클라이언트와 서버는 서로 독립적으로 동작하며, 클라이언트는 API 요청을 보내고, 서버는 요청을 처리하여 응답을 반환합니다.

✅ 무상태성 (Stateless)
✔️ 서버는 클라이언트의 상태를 저장하지 않습니다. 즉, 요청마다 필요한 모든 정보를 포함해야 합니다.
✔️ 예를 들어, GET /users/1 요청을 하면, 서버는 해당 요청만 처리할 뿐, 이전 요청의 정보를 기억하지 않습니다


✅ 캐시 가능 (Cacheable)
✔️ HTTP 기반이므로 캐싱을 지원하며, 성능 향상을 위해 적절한 캐싱 정책을 설정할 수 있습니다

✅ 일관된 인터페이스 (Uniform Interface)
✔️ RESTful API는 일관된 리소스(URL)와 HTTP 메서드를 사용하여 직관적인 인터페이스를 제공합니다.

✅ 계층화 시스템 (Layered System)
✔️ 클라이언트는 중간 서버(예: 로드 밸런서, 프록시, 게이트웨이)를 알 필요 없이 요청을 보낼 수 있습니다.

---

2. REST API의 주요 구성 요소

REST API는 주로 다음과 같은 요소로 구성됩니다.

✅ 리소스 (Resource)

• API에서 데이터의 개별적인 엔터티를 의미하며, 일반적으로 URI(Uniform Resource Identifier) 를 통해 식별됩니다.
• 예: https://api.example.com/users/1 (사용자 ID가 1인 사용자 데이터)

✅ HTTP 메서드 (CRUD 매핑)

• REST API는 HTTP 메서드를 사용하여 리소스를 조작합니다.

HTTP 메서드	동작	설명
GET	조회	리소스를 조회 (읽기 전용)
POST	생성	새로운 리소스를 생성
PUT	수정	기존 리소스를 전체 업데이트
PATCH	부분 수정	리소스의 일부 속성만 변경
DELETE	삭제	리소스를 삭제

예를 들어, 사용자 정보를 조회하는 API는 다음과 같이 요청할 수 있습니다.

GET /users/1

 

응답

{ "id": 1, "name": "홍길동", "email": "hong@example.com" }

 

---

3. REST API 예제

✅ 사용자 목록 조회

GET /users

응답

 

[ {"id": 1, "name": "홍길동", "email": "hong@example.com"}, {"id": 2, "name": "김철수", "email": "kim@example.com"} ]

 ✅  사용자 생성

POST /users Content-Type: application/json { "name": "이영희", "email": "lee@example.com" }

 

응답

201 Created Location: /users/3

✅  사용자 정보 수정

PUT /users/1 Content-Type: application/json { "name": "홍길동", "email": "hong_new@example.com" }

 

응답

200 OK

✅  사용자 삭제

DELETE /users/1

 

응답

204 No Content

 

---

4. REST API의 장점과 단점

✅ 장점

• 언어 및 플랫폼 독립적: HTTP 기반이므로 다양한 언어에서 사용 가능 (Python, JavaScript, Java 등)
• 구조적이고 직관적: URL 및 HTTP 메서드만으로 API의 역할을 쉽게 이해할 수 있음
• 확장성이 좋음: 클라이언트-서버가 분리되어 개발 및 확장이 용이함
• 캐싱을 활용 가능: HTTP 캐시를 활용하여 성능을 향상시킬 수 있음

❌ 단점

• Over-fetching & Under-fetching 문제: 필요한 데이터만을 요청하기 어려움 (GraphQL은 이를 해결)
• 복잡한 요청 처리 시 한계: 대량의 데이터를 조작하거나 여러 엔드포인트를 한 번에 호출해야 하는 경우 부담이 될 수 있음
• 무상태성으로 인해 클라이언트가 데이터를 계속 포함해야 함: 인증 정보 등 추가적인 부담이 발생할 수 있음

---

5. REST API vs. 다른 API 방식

특징	REST API	SOAP API	GraphQL
프로토콜	HTTP	HTTP, SMTP 등	HTTP
데이터 포맷	JSON, XML	XML	JSON
유연성	높음 (다양한 클라이언트 지원)	낮음 (엄격한 구조)	매우 높음 (필요한 데이터만 가져옴)
학습 곡선	쉬움	어려움	중간
성능	보통 (과다한 데이터 포함 가능)	낮음 (XML 오버헤드)	높음 (불필요한 데이터 제거)

---

6. RESTful API를 설계할 때의 Best Practices

✅  명확하고 직관적인 URL 사용

• GET /users → ✅ 올바름
• GET /getUsers → ❌ 잘못된 예 (HTTP 메서드와 중복)
• POST /createUser → ❌ 잘못된 예 (RESTful하지 않음)

✅  플러럴(복수형) 사용

• GET /users → ✅ 올바름
• GET /user → ❌ 잘못된 예

✅  HTTP 상태 코드 사용

• 200 OK: 성공
• 201 Created: 리소스 생성됨
• 204 No Content: 삭제 성공
• 400 Bad Request: 잘못된 요청
• 401 Unauthorized: 인증 실패
• 404 Not Found: 리소스 없음
• 500 Internal Server Error: 서버 오류

✅  필요한 데이터만 포함하기

• Over-fetching을 방지하고, 불필요한 필드를 줄여 API 응답 크기를 최소화

✅  보안 고려

• HTTPS 사용
• OAuth2, JWT 등을 활용한 인증 및 권한 부여

---

REST API는 간결하고 확장성이 뛰어난 API 설계 방식으로, 대부분의 웹 애플리케이션과 모바일 앱에서 널리 사용됩니다. HTTP 메서드와 리소스 기반 설계를 이해하고, Best Practices를 따르면 유지보수성과 성능을 높일 수 있습니다.

REST API를 실무에서 구현할 때는 보안과 성능도 함께 고려해야 하며, 필요에 따라 GraphQL 같은 대체 기술도 검토할 수 있습니다. 🚀