[배경]
우리가 아침에 일어나서 카카오톡으로 메시지를 보내고, 네이버로 날씨를 확인하고, 유튜브로 영상을 볼 때마다, 보이지 않는 곳에서 RESTful API라는 기술이 열심히 일하고 있다는 걸 아셨나요? 이 작은 기술이 없다면 우리가 사랑하는 앱들이 멈춰버릴지도 모릅니다. RESTful API는 사실 우리가 매일 쓰는 인터넷의 기본 규칙, HTTP에서 태어났습니다. 단순히 'GET'이나 'POST' 같은 단어로 시작된 이 기술이 이제는 전 세계 서버와 앱을 연결하는 다리가 되었습니다. 이 작은 단어들이 어떻게 세상을 움직이는 걸까요?
[내용]
1. RESTful API란?
RESTful API는 REST(Representational State Transfer) 아키텍처 스타일을 따르는 애플리케이션 프로그래밍 인터페이스(API)입니다. REST는 웹의 기본 원칙(HTTP 프로토콜, URI, 메서드 등)을 활용하여 시스템 간 데이터를 주고받는 방식을 정의한 설계 방식입니다. RESTful API는 주로 클라이언트(예: 웹/모바일 앱)와 서버 간 통신을 위해 사용됩니다. 쉽게 말해, RESTful API는 인터넷 상에서 자원을 주고받기 위한 간단하고 표준화된 방법이라고 생각하면 됩니다.
2. RESTful API 구성 요소
1) 자원(Resource)
- REST에서는 모든 데이터를 "자원"으로 취급하며, URI(Uniform Resource Identifier)로 식별합니다.
- 예: https://api.example.com/users/123은 ID가 123인 사용자를 나타냅니다.
2) HTTP 메서드
- 자원에 대해 수행할 작업을 정의합니다.
- GET: 자원을 조회 (예: 사용자 목록 가져오기)
- POST: 자원을 생성 (예: 새 사용자 추가)
- PUT: 자원을 수정 (예: 사용자 정보 업데이트)
- DELETE: 자원을 삭제 (예: 사용자 삭제)
3) 상태 코드 (Status Code)
- 요청의 결과를 나타냅니다.
- 200 OK: 성공
- 201 Created: 자원 생성 성공
- 400 Bad Request: 잘못된 요청
- 404 Not Found: 자원을 찾을 수 없음
- 500 Internal Server Error: 서버 오류
4) 헤더 (Header)
- 요청/응답에 대한 메타데이터를 포함합니다.
- 예: Content-Type: application/json (데이터 형식이 JSON임을 나타냄)
5) 페이로드 (Payload)
- 요청 또는 응답에 포함된 실제 데이터입니다.
- 주로 JSON 또는 XML 형식으로 전송됩니다.
3. RESTful API의 핵심 원칙
1) 클라이언트-서버 구조 (Client-Server)
- 클라이언트(요청을 보내는 쪽)와 서버(요청을 처리하는 쪽)가 명확히 분리되어야 합니다. 이렇게 분리하면 확장성(Scalability)이 높아지고, 관리하기 쉬워진다는 장점이 있습니다.
- 예: 웹 브라우저(클라이언트)가 서버에 데이터를 요청하면 서버가 응답을 보냅니다.
2) 무상태성 (Stateless)
- 각 요청은 독립적이어야 하며, 서버는 이전 요청의 상태를 기억하지 않습니다.
- 즉, 클라이언트가 필요한 모든 정보를 요청에 포함해야 합니다.
- 예: 로그인 상태를 유지하려면 매 요청마다 인증 토큰을 보내야 합니다.
3) 캐시 가능 (Cacheable)
- 응답 데이터에 캐시 가능 여부를 명시하여 클라이언트가 데이터를 재사용할 수 있게 합니다.
- HTTP 헤더(예: Cache-Control)를 통해 구현됩니다.
4) 계층화 시스템 (Layered System)
- 클라이언트는 서버와 직접 통신하는지, 중간에 프록시나 게이트웨이가 있는지 알 필요가 없습니다.
- 보안, 로드 밸런싱 등을 위해 계층이 추가될 수 있습니다.
5) 일관된 인터페이스 (Uniform Interface)
- 자원(Resource)을 식별하고 조작하는 방식이 일관적이어야 합니다.
- 이를 위해 URI로 자원을 식별하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용합니다.
- 일관된 인터페이스에는 다음과 같은 규칙이 있습니다.
(1) 리소스(자원)는 URI로 표현해야 합니다!
👉 예를 들어, 유저 정보 API를 만든다고 하면?
❌ 잘못된 예시:
GET /getUsers?id=123✅ RESTful한 예시:
GET /users/123📌 → 명사를 사용하고, 계층적인 구조로 표현하는 것이 중요합니다.
(2) HTTP 메서드를 활용해야 합니다!
| 메서드 | 설명 | 예시 |
| GET | 데이터를 조회할 때 | GET /users/123 |
| POST | 새로운 데이터를 추가할 때 | POST /users |
| PUT | 데이터를 수정할 때 | PUT /users |
| DELETE | 데이터를 삭제할 때 | DELETE /users |
📌 이렇게 하면 코드를 보지 않아도 직관적으로 API의 기능을 알 수 있습니다.
(3) 응답 데이터는 기본데이터 포맷으로 JSON 형식을 사용합니다!
👉 RESTful API는 데이터를 주고받을 때 JSON 형식을 많이 사용합니다.
{
"id": 123,
"name": "홍길동",
"age": 18
}
📌 JSON이 가볍고 읽기 쉬워서, RESTful API의 기본 데이터 포맷으로 사용됩니다.
6) 코드 온 디맨드 (Code on Demand, 선택적)
- 서버가 클라이언트에 실행 가능한 코드를 보낼 수 있습니다(예: JavaScript).
- 이 원칙은 필수가 아니며 잘 사용되지 않습니다.
4. RESTful API의 장단점
1) 장점
- 확장성: 무상태성과 계층화 덕분에 서버를 쉽게 확장할 수 있습니다.
- 단순성: HTTP를 사용하므로 학습 곡선이 낮고 기존 웹 인프라와 호환됩니다.
- 유연성: 다양한 데이터 형식(JSON, XML 등)을 지원합니다.
2) 단점
- 복잡한 쿼리 처리 어려움: 단순 CRUD(Create, Read, Update, Delete) 외 복잡한 작업은 구현이 까다로울 수 있습니다.
- 오버페칭/언더페칭: 필요 이상의 데이터가 오거나(오버페칭), 필요한 데이터가 부족할 수 있습니다(언더페칭). 이를 해결하려면 GraphQL 같은 대안이 사용되기도 합니다.
5. RESTful API 설계 모범 사례
- 명확한 URI 설계
- /users, /users/123처럼 자원을 계층적으로 표현하세요.
- 동사는 넣지 말고(예: /getUsers ❌), 자원 이름만 사용하세요(예: /users ✅).
- 적절한 HTTP 메서드 사용
- 조회는 GET, 생성은 POST 등 작업에 맞게 사용하세요.
- 버전 관리
- API가 업데이트될 경우를 대비해 URI에 버전을 포함하세요(예: /v1/users).
- 에러 처리
- 적절한 상태 코드와 에러 메시지를 반환하세요.
[결론]
RESTful API는 웹에서 데이터를 주고받는 효율적인 방법입니다. 핵심 특징으로는 자원을 URI로 표현하고, HTTP 메서드를 활용하는 것이 핵심입니다. JSON을 주로 활용해 일관된 인터페이스를 제공해야 하며 최근에는 GraphQL, gRPC, WebSocket 등 다양한 대안이 등장하고 있으며, 각각의 장점과 한계를 이해하는 것이 중요합니다. 다음에는 RESTful API를 기본 개념으로 익힌 후, 최신 기술 트렌드도 함께 공부하겠습니다.
[출처 및 참조]
'spring' 카테고리의 다른 글
| [HTTP] 개발을 위한 꼭 알아야 하는 상태 코드 (0) | 2025.03.21 |
|---|---|
| [Spring] 단 한 줄로 트랜잭션 제어하기 - @Transactional의 강력한 힘 (0) | 2025.03.14 |
| [Spring] AOP 포인트컷 문법 및 용어정리 (0) | 2024.09.10 |
| [Spring] 너만 모르는 Spring 과 Spring Boot 의 차이 (2) | 2024.09.02 |
| [Spring] 스프링의 삼각형: IoC/DI, AOP, PSA를 통한 클린 코드와 유지보수성 향상 (1) | 2024.08.28 |
