[ CS > Network ]
[API] RESTful API 아키텍처
RESTful API 아키텍처
REST(Representational State Transfer)는 Web을 개발하는데 지침을 제공하고 그 구조를 설명하기 위해 만들어진 소프트웨어 아키텍처 스타일이다.
1. Rest 아키텍처 특징
Restful API의 핵심은 URL을 Endpoint로 바라보는 것이 아니라 하나의 자원으로 바라보는 것이고, 일관성을 가져서 예측 가능하게 되는 것이다. 아래는 Rest 아키텍처에서 가지는 특성이라고 한다.
1.1 Stateless 무상태성
클라이언트-서버 요청에서 클라이언트 정보가 저장되지 않고, 각 요청은 분리되어야 한다.
1.2 Client-Server 구조
클라이언트, 서버, 리소스로 구성되어 있으며 HTTP로 요청이 이루어진다.
1.3 데이터 캐싱
캐싱이 가능하도록 하여 클라이언트-서버간 상호작용을 최소화한다.
1.4 일관된 인터페이스
리소스 식별이 가능해야 하며, 클라이언트에 전송된 표현과 구분되어야한다.
그리고 수신하는 표현을 통해 리소스가 조작되어야 한다.
클라이언트는 자기 서술적 메시지에 정보를 어떻게 처리해야 할지 설명하는 정보가 충분히 포함되어야 한다.(Content-type, method, encoding 등)
1.5 레이어드 아키텍처 지원
서버는 계층 구조(보안, 로드밸런싱 등)로 구성하는 계층화된 시스템을 가질 수 있다.
1.6 코드 온 디맨드
요청을 받으면 서버에서 클라이언트로 실행 가능한 코드를 전송하여 클라이언트 기능을 확장할 수 있다.
2.메서드와 상태 정리
Restful API에서는 자원에 대한 행위를 HTTP 메서드를 통해 나타내어 서버에서 이 메서드에 따라 처리하고, Response로 상태 코드를 전달해 응답의 상태를 표현한다.
2.1 메서드
메서드 | 설명 | 주된 용도 | 멱등성 (Idempotent) | 안전성 (Safe) | 예시 URI |
|---|---|---|---|---|---|
GET | 리소스를 조회 | 데이터 조회 | ✅ 예 (같은 요청 여러 번 해도 결과 동일) | ✅ 예 (서버 상태 변경 없음) | /users/1 |
POST | 리소스를 생성 | 데이터 추가 | ❌ 아니오 | ❌ 아니오 | /users |
PUT | 리소스를 전체 수정 | 데이터 전체 업데이트 | ✅ 예 | ❌ 아니오 | /users/1 |
PATCH | 리소스를 일부 수정 | 데이터 일부 업데이트 | ❌ 일반적으로 아니오 (서버 구현에 따라 다름) | ❌ 아니오 | /users/1 |
DELETE | 리소스를 삭제 | 데이터 삭제 | ✅ 예 (이미 삭제된 경우에도 동일한 응답 가능) | ❌ 아니오 | /users/1 |
OPTIONS | 지원하는 메서드 조회 | CORS 사전 요청 등 | ✅ 예 | ✅ 예 | /users |
HEAD | 리소스의 헤더만 조회 (본문 없음) | 메타데이터 확인 | ✅ 예 | ✅ 예 | /users/1 |
2.2 상태
상태 | 상태 코드 | 의미 | 설명 | 사용 예시 |
|---|---|---|---|---|
(2xx) | 200 OK | 요청 성공 | GET, PUT, PATCH, DELETE 등에 사용 | 데이터 조회 성공 |
201 Created | 생성됨 | POST 요청으로 리소스 생성 시 사용 | 회원가입, 글 작성 등 | |
204 No Content | 내용 없음 | 성공했지만 응답 본문이 없을 때 | DELETE, PUT 성공 후 응답 없음 | |
(3xx) | 301 Moved Permanently | 영구 이동 | 리소스가 영구적으로 이동 | URL 변경 안내 |
302 Found | 임시 이동 | 리소스가 임시로 다른 위치에 있음 | 로그인 후 리디렉션 | |
304 Not Modified | 변경 없음 | 캐시된 리소스를 그대로 사용 가능 | 조건부 GET (If-Modified-Since 등) | |
(4xx) | 400 Bad Request | 잘못된 요청 | 유효하지 않은 파라미터 등 | 필드 누락, JSON 파싱 실패 |
401 Unauthorized | 인증 필요 | 로그인 필요 또는 토큰 오류 | JWT 없음/만료 | |
403 Forbidden | 접근 금지 | 권한이 없는 경우 | 관리자 전용 접근 | |
404 Not Found | 리소스 없음 | 존재하지 않는 URI 요청 | 잘못된 ID로 조회 시 | |
409 Conflict | 충돌 | 중복 리소스 생성 시 등 | 동일 ID 중복 생성 등 | |
422 Unprocessable Entity | 처리할 수 없음 | 형식은 맞지만 의미가 잘못됨 | 폼 검증 실패 등 | |
(5xx) | 500 Internal Server Error | 내부 서버 오류 | 서버 내부 예외 발생 | 예상치 못한 에러 |
502 Bad Gateway | 게이트웨이 오류 | 서버가 잘못된 응답 수신 | 프록시, 게이트웨이 문제 | |
503 Service Unavailable | 서비스 불가 | 서버 점검 중 또는 과부하 | 서버 다운, 유지보수 | |
504 Gateway Timeout | 게이트웨이 타임아웃 | 응답 지연 | 백엔드 응답 지연 시 |
3. 리차드슨 성숙도 모델(Richardson Maturity Model)
리차드슨(Richardson)은 Rest API를 잘 적용하기 위해 4단계의 성숙도 모델을 정의했다.
