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단계의 성숙도 모델을 정의했다.