728x90
** 2025.02.28 보충 내용 추가 **
📌 RESTful API란?
- RESTful API는 REST (Representational State Transfer) 아키텍처 스타일을 따르는 API
- REST는 웹 서비스 설계를 위한 원칙이며, RESTful API는 이 원칙을 준수하여 설계된 API
🔹 REST란? (Representational State Transfer)
- 자원의 표현을 이용하여 상태(정보)를 주고받는 것
- 여기서 자원이란, 소프트웨어가 관리하는 모든 것을 의미(자원의 표현은 자원을 나타내기 위한 이름을 의미)
- 일반적으로 자원의 상태를 나타내기 위해 JSON 포맷을 사용한다.
- REST는 네트워크 상에서 클라이언트와 서버의 통신 방식 중 하나이며, HTTP 프로토콜을 사용한다.
- HTTP URI를 활용하여 자원을 명시하고 HTTP METHOD(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD 연산을 적용하는 것을 의미
- HTTP URI(Uniform Resource Identifier): 리소스를 나타내는 모든 식별자 (URL, URN 포함한 개념)
- HTTP URI를 활용하여 자원을 명시하고 HTTP METHOD(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD 연산을 적용하는 것을 의미
🔹 API란? (Application Programming Interface)
- 소프트웨어 간의 상호작용을 가능하게 하는 인터페이스
- 프로그램 또는 서비스 간 데이터를 주고받을 수 있도록 돕는 기능
🔹 쉽게 말하면
- API는 소프트웨어 간의 대화 방법을 정의한 것.
- 개발자가 직접 데이터를 가져오거나 저장하지 않아도, API를 통해 다른 서비스에서 데이터를 주고받을 수 있다.
🔹 API는 다양한 형태로 구현될 수 있지만, 가장 널리 쓰이는 방식이 REST 아키텍처 스타일이다.
📌 REST 아키텍처 스타일이란?
- 웹에서 API를 설계하는 원칙(스타일) 중 하나로, HTTP 기반으로 동작하는 자원(Resource) 중심의 설계 원칙
🔹 쉽게 말하면
- 웹에서 데이터를 주고받을 때 지켜야 할 설계 원칙(스타일)
- 특정 프로토콜이나 언어에 의존하지 않고 HTTP를 활용하여 데이터를 주고받음.
- URI을 통해 자원을 명확히 식별하고, HTTP 메서드 (GET, POST, PUT, DELETE) 를 사용하여 조작.
🔹 REST의 6가지 원칙
- 클라이언트-서버 구조 (Client-Server)
- 프론트엔드(React, Android, iOS)와 백엔드(FastAPI, Spring Boot 등)를 독립적으로 운영할 수 있도록 분리.
- 무상태성 (Stateless)
- 서버는 클라이언트의 상태를 저장하지 않음. 모든 요청은 독립적으로 처리됨.
- 확장성 유리, 부하 분산 쉬움
- 캐시 가능 (Cacheable)
- 서버 응답을 캐시할 수 있어 성능을 최적화할 수 있음.
- 계층적 구조 (Layered System)
- API 서버는 보안, 로드 밸런서, 데이터베이스 등을 계층적으로 구성할 수 있음.
- 일관된 인터페이스 (Uniform Interface)
- API의 설계가 일관되게 유지되어야 함. (예: HTTP 메서드 활용)
- 코드 온 디맨드 (Code on Demand, 선택적)
- 필요하면 서버가 실행 가능한 코드를 클라이언트에 제공할 수 있음. 유연성 확보 (거의 사용되지 않음)
📌 REST의 구성 요소
1. 자원(Resource): URI로 식별되는 모든 대상
2. 표현(Representation): JSON, XML 등으로 자원의 상태를 나타냄
3. 메서드(Method): HTTP 메서드(GET, POST 등)로 자원 조작
4. URI: 자원의 위치(식별자)
5. 상태 전이(HATEOAS): 서버 응답에, 다음 단계에서 호출할 수 있는 관련 링크들을 함께 제공하는 방식 (이론적으로는 REST의 핵심 요소지만, 실무에서는 대부분 생략한다.)
* HATEOAS (Hypermedia As The Engine Of Application State)
: 서버가 응답할 때, 다음에 호출할 수 있는 API 링크를 응답에 포함시키는 방식
ex) 주문 상세 조회 응답에 "주문 취소 링크"를 함께 제공
📌 RESTful API의 구성 요소
RESTful API는 리소스를 URI로 식별하고, 해당 리소스를 HTTP 메서드를 통해 조작하는 방식으로 구성된다.
1. 리소스 (Resource)
- API에서 관리하는 대상(사용자, 게시글, 상품 등)을 의미하며, HTTP URI을 통해 식별된다.
- 예시: /users, /products, /orders
2. HTTP 메서드 (CRUD 작업)
- RESTful API는 HTTP 메서드를 활용하여 리소스를 조작한다.
| HTTP 메서드 | 설명 | 예제 |
| GET | 데이터 조회 | GET /users/1 (ID가 1인 사용자 조회) |
| POST | 데이터 생성 | POST /users (새 사용자 추가) |
| PUT | 데이터 전체 수정 | PUT /users/1 (ID가 1인 사용자 정보 전체 수정) |
| PATCH | 데이터 일부 수정 | PATCH /users/1 (ID가 1인 사용자 정보 일부 수정) |
| DELETE | 데이터 삭제 | DELETE /users/1 (ID가 1인 사용자 삭제) |
* HTTP 상태 코드 (Response Status Code)
- 서버의 응답 상태를 나타내는 코드.
| 상태 | 코드의미 |
| 200 OK | 정상 응답 |
| 201 Created | 리소스 생성 완료 |
| 400 Bad Request | 잘못된 요청 |
| 401 Unauthorized | 인증 실패 |
| 404 Not Found | 리소스 없음 |
| 500 Internal Server Error | 서버 내부 오류 |
3. 표현(Representation of Resource)
- 클라이언트가 자원의 상태(정보)에 대한 조작을 요청하면 서버는 이에 적절한 응답을 보낸다.
- REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
- JSON 또는 XML 통해 데이터를 주고 받는 것이 일반적이다.
🔹 RESTful API의 특징
- 리소스(Resource) 중심 설계: URL을 통해 자원을 명확하게 식별.
- HTTP 메서드 활용: 데이터를 CRUD(생성, 읽기, 수정, 삭제)할 때 적절한 HTTP 메서드를 사용.
📌 RESTful API는 왜 쓰는가?
1) 확장성과 유지보수성이 좋음
- 프론트엔드와 백엔드가 독립적으로 개발될 수 있음.
- 새로운 기능을 추가해도 기존 API를 변경할 필요 없이 쉽게 확장 가능.
2) 다양한 플랫폼과 연동 가능
- 모바일(Android, iOS), 웹(React, Vue.js), IoT(스마트기기) 등 어디서든 API를 사용할 수 있음.
3) 일관된 설계 원칙 제공
- RESTful API는 자원을 중심으로 한 일관된 설계 원칙을 따르므로, 개발자가 쉽게 이해하고 사용할 수 있음.
4) 보안 및 성능 향상
- 무상태성 덕분에 서버 부하가 줄어들고, 캐싱을 활용하면 성능 최적화 가능.
- JWT, OAuth 같은 인증 방식을 쉽게 적용할 수 있음.
📌 RESTful API의 장점과 단점
✅ 장점
- 클라이언트-서버 분리: 프론트엔드와 백엔드를 독립적으로 개발 가능.
- 유연성: 다양한 플랫폼과 연동이 쉬움. (HTTP 프로토콜을 따르는 모든 플랫폼에서 사용 가능)
- 확장성: API를 쉽게 확장할 수 있음.
- 캐싱 가능: 성능 최적화 가능.
- CURL, Postman을 사용하여 간단하게 테스트할 수 있다.
- API 변경 시에도 하위호환성 확보 쉬움
* JSON과 같은 텍스트 포맷은 자기 서술적이며, 메시지를 받는 측(소비자)이 자신이 관심이 있는 값만 선택해서 사용하고,
나머지는 무시할 수 있어, API 응답 구조가 일부 변경되더라도 하위 호환성을 유지하기 쉽다.
하지만, 메시지가 다소 길다는 것이 단점이다. 메시지가 길다면 네트워크 트래픽을 더욱 사용하며 전송 속도가 느릴 수 있으며, 메시지를 해석하는 데에 오버헤드가 발생할 수 있다.
❌ 단점
- 무상태성: 클라이언트 상태를 유지하지 않아 일부 서비스에서 비효율적일 수 있음.
- 과도한 요청 발생 가능: 특정 데이터를 얻기 위해 여러 API 호출이 필요할 수 있음 (GraphQL이 이를 보완함)
- 요청-응답 방식의 통신만 지원한다.
- API 수정 시 클라이언트 수정 필요할 가능성 높음 -> 버전 관리 필수
📌 RESTful API와 RESTful하지 않은 API의 차이
- RESTful API는 리소스를 URL로 표현하고 HTTP 메서드를 적절히 사용하는 것이 특징
- RESTful하지 않은 API는 자원(Resource)이 아닌 동작(Action)을 중심으로 설계되며,
URL에 동사를 직접 포함하거나, HTTP 메서드와 무관하게 모든 요청을 POST로만 처리하는 방식이 대표적이다.
| 구분 | RESTful API | RESTful하지 않은 API |
| URL | /users/1 | /getUser?id=1 |
| HTTP 메서드 | GET, POST, PUT, DELETE 사용 | 모든 요청을 POST로 처리 |
| 리소스 중심 | users, products 등 명확한 리소스 명시 | 동작 중심 (getUser, updateUser) |
| 응답 형식 | JSON | XML 또는 HTML |
📌 RESTful API vs GraphQL
🔹 GraphQL과 비교하는 이유
- RESTful API는 웹에서 데이터를 주고받을 때 가장 많이 사용되는 방식이지만, GraphQL이 REST의 단점을 보완하면서 등장했기 때문
1. RESTful API와 GraphQL의 차이점
| 비교 항목 | RESTful API | GraphQL |
| 데이터 요청 방식 | 여러 개의 엔드포인트 필요 | 단일 엔드포인트 사용 |
| 오버페칭 (Over-fetching) |
불필요한 데이터까지 가져옴 | 필요한 데이터만 가져옴 |
| 언더페칭 (Under-fetching) |
필요한 데이터가 부족하면 추가 요청 필요 | 한 번의 요청으로 원하는 데이터 제공 |
| HTTP 메서드 | GET, POST, PUT, DELETE 활용 | 모든 요청이 POST로 처리됨 |
| 응답 형식 | 고정된 JSON 구조 | 클라이언트가 원하는 데이터만 선택 가능 |
| 유연성 | API가 정해진 응답을 반환 | 클라이언트가 원하는 데이터 구조를 요청 가능 |
| 캐싱 | HTTP 캐싱 (Cache-Control, CDN) 활용 가능 | 직접 캐싱 로직을 구현해야 함 |
2. RESTful API vs GraphQL: 언제 사용해야 할까?
| 사용 조건 | RESTful API가 유리 | GraphQL이 유리 |
| 단순한 데이터 제공 | ✅ | ❌ |
| 데이터가 자주 바뀌지 않음 | ✅ | ❌ |
| 캐싱 필요 (CDN 활용) | ✅ | ❌ |
| 다양한 데이터 조합 요청 | ❌ | ✅ |
| 대량의 데이터 제공 (Over-fetching 방지) | ❌ | ✅ |
| 프론트엔드가 원하는 데이터만 가져가야 함 | ❌ | ✅ |
📌 RESTful API 구현 방법
(1) Flask + FastAPI (Python)
- Flask 또는 FastAPI를 사용하여 RESTful API를 구현 가능.
(2) Spring Boot (Java)
- Java 환경에서는 Spring Boot를 활용하여 RESTful API를 쉽게 만들 수 있음.
(3) Express.js (Node.js)
- Node.js 기반에서는 Express.js를 사용하여 RESTful API를 개발할 수 있음.
📌 Reference
반응형
'🇫 Framework > fastAPI' 카테고리의 다른 글
| Uvicorn / ASGI vs WSGI (0) | 2025.02.10 |
|---|