오늘의 주제는 RESTful API이며 개발자라면 누구나 알고 있겠지만 좀 더 깊게 다뤄보고자 한다. RESTful API는 웹 애플리케이션 간 데이터를 주고받기 위해 널리 사용되는 설계 방식으로, HTTP 프로토콜을 기반으로 한다. RESTful API를 설계할 때는 리소스를 중심으로 설계하고, 일관성 있는 규칙을 준수하는 것이 중요하다. 나의 경우 어느정도 알고있다고 생각했지만 전 직장 PM으로 부터 많은 지적을 받고 피드백을 받으며 개선이 되었지만 개발을 하다보면 편의상 무시하게 되는 경우가 종종 있었다. 그렇기에 좀 더 깊게 이해하고 단순한 API를 개발하더라도 신중하게 고민하고 개발하는 습관화가 되어야 겠다고 생각했다.
REST(Representational State Transfer)는 로이 필딩(Roy Fielding)이 정의한 웹 아키텍처 스타일로, HTTP 프로토콜을 활용해 클라이언트와 서버 간의 데이터를 교환한다. REST는 리소스를 URL로 표현하고, HTTP 메서드를 사용해 이를 조작한다는 점에서 직관적이고 이해하기 쉬운 구조를 제공한다.
RESTful API는 REST의 설계 원칙을 기반으로 구축된 API로, 다음과 같은 주요 특징을 갖는다:
- 리소스 중심 설계: 데이터와 작업을 리소스 단위로 관리한다.
- HTTP 메서드 활용: GET, POST, PUT, DELETE 등 HTTP 메서드를 사용해 리소스를 조작한다.
- 상태 비저장성: 각 요청은 필요한 데이터를 포함하며, 독립적으로 처리된다.
RESTful API는 다음과 같은 설계 원칙을 따른다. 각 원칙을 설계 예시와 함께 살펴본다.
API의 구조는 명확하고 일관성이 있어야 한다. 각 리소스는 고유한 URL로 식별되며, URL은 동사보다는 명사를 사용해야 한다.
이유를 간단하게 정리하면 RESTful API는 리소스 중심 설계로 명사는 리소스를 나타내는 데 적합하지만, 동사의 경우 리소스가 아니라 작업을 표현한다.
- 잘못된 예: "/getUser" (동사 사용)
- 올바른 예: "/users" (명사 사용)
GET /users # 전체 사용자 목록 조회
GET /users/123 # ID가 123 사용자 조회
POST /users # 새 사용자 생성
PUT /users/123 # ID가 123 사용자 정보 전체 수정
DELETE /users/123 # ID가 123 사용자 삭제서버는 클라이언트의 상태를 저장하지 않는다. 모든 요청은 필요한 데이터를 포함하며, 독립적으로 처리된다.
클라이언트가 API 호출 시 인증 정보를 매번 포함해야 한다.
GET /users/devnine
Authorization: Bearer <access_token>API의 응답은 캐싱이 가능해야 한다. 이를 위해 HTTP 헤더를 활용해 캐싱 가능 여부를 명시한다.
GET /users/123
Cache-Control: max-age=3600위와 같이 설정하면 클라이언트는 1시간(3600초) 동안 동일한 요청에 대해 캐시된 데이터를 사용할 수 있다.
클라이언트는 중간 계층(프록시, 게이트웨이 등)을 인지하지 않고 서버와 통신한다. 이를 통해 로드 밸런싱, 캐싱 등이 가능해진다.
API 응답에 추가 작업을 위한 링크를 포함하여 클라이언트가 더 많은 작업을 수행할 수 있도록 한다. 이를 통해 API의 탐색성이 높아진다.
{
"id": 123,
"name": "devnine",
"links": {
"self": "/users/123",
"update": "/users/123",
"delete": "/users/123"
}
}RESTful API는 HTTP 메서드와 상태 코드를 사용해 요청과 응답의 의미를 명확히 전달한다.
| HTTP 메서드 | 역할 | 예시 |
|---|---|---|
| GET | 리소스 조회 | "/users" (전체 사용자 조회) |
| POST | 새로운 리소스 생성 | "/users" (새 사용자 생성) |
| PUT | 기존 리소스 수정 | "/users/123" (ID가 123인 사용자 수정) |
| DELETE | 리소스 삭제 | "/users/123" (ID가 123인 사용자 삭제) |
| PATCH | 리소스의 일부만 수정 | "/users/123" (ID가 123인 사용자 부분 수정) |
RESTful API는 요청 결과를 명확히 나타내기 위해 상태 코드를 사용한다.
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 200 | 성공 | 요청이 정상적으로 처리됨 |
| 201 | 리소스 생성 성공 | POST 요청으로 새 리소스 생성 완료 |
| 204 | 요청 성공, 응답 본문 없음 | DELETE 요청 성공 |
| 400 | 잘못된 요청 | 클라이언트 오류 |
| 401 | 인증 실패 | 유효한 인증 자격 증명 필요 |
| 404 | 리소스 없음 | 요청한 리소스를 찾을 수 없음 |
| 500 | 서버 오류 | 서버에서 요청 처리 중 오류 발생 |
- 직관적이고 간결한 설계: URL과 HTTP 메서드를 활용하여 이해하기 쉬운 API 설계가 가능하다.
- 이식성과 호환성: HTTP 기반이므로 다양한 플랫폼에서 쉽게 사용할 수 있다.
- 확장성: 리소스를 추가하거나 확장하기 쉽다.
- 캐싱 가능: HTTP 캐싱을 통해 성능을 향상시킬 수 있다.
- 복잡한 트랜잭션 처리 부족: 다중 작업이 필요한 경우 구현이 복잡해질 수 있다.
- 무상태성의 부담: 요청마다 인증 정보를 포함해야 하므로 네트워크 트래픽이 증가할 수 있다.
- HATEOAS 적용 어려움: 대부분의 구현에서 HATEOAS를 완전히 지원하지 않는다.
RESTful API는 간결하고 직관적인 설계 방식으로, 클라이언트와 서버 간의 데이터 교환을 효율적으로 처리할 수 있는 강력한 도구다. HTTP 메서드와 상태 코드를 적절히 활용하여 표준화된 인터페이스를 제공하며, 이를 통해 개발자와 사용자 모두에게 직관적인 경험을 제공한다. 하지만 설계 원칙을 잘못 적용하거나 복잡한 트랜잭션을 처리할 때는 적합하지 않을 수 있으므로, 상황에 맞는 적절한 설계와 사용이 중요하다.