[ Spring ] REST API란? – 설계 원칙, HTTP 메서드, 상태코드 정리

1. REST API란?

• Representational State Transfer(REST)라는 아키텍처 스타일을 따르는 웹 서비스
• 웹의 리소스를 일관된 방식으로 정의하고 접근하기 위한 아키텍처 방식
• HTTP 프로토콜을 사용해 클라이언트와 서버간에 데이터를 교환
• 웹서비스의 모든것을 자원으로 간주하고, 자원은 URI(Uniform Resource Identifier)를 통해 식별됨

❓ASGI
- Python 웹 프레임워크에서 비동기 처리를 지원하는 서버 인터페이스 표준
- ASGI를 지원하는 서버 : Uvicorn, FastAPI

 

2. REST API 설계 원칙

1) 자원 기반의 URI 설계

• 자원은 명사 복수형으로 표현

/users, /products, /orders

• 모든 자원은 고유한 URI(식별자) 사용

/users/123  (ID가 123인 사용자)

• 자원 간의 관계를 계층 구조로 표현

/users/123/orders (ID가 123인 사용자의 주문 목록)

• 컬렉션과 개별자원 구분

컬렉션: /users (모든 사용자 목록) 
개별 자원: /users/123 (ID가 123인 사용자)

• URI는 소문자 사용하고 하이픈(-)으로 여러 단어 구분
• 자원의 상태(State)와 표현(Representation) 분리

 

2) HTTP  주요 메서드

메서드	의미	설명	멱등성
GET	조회	리소스 조회	멱등성 O, 캐싱 가능
POST	생성	리소스 생성	멱등성 X
PUT	전체 수정	리소스 전체 교체	멱등성 O
PATCH	부분 수정	리소스 일부 수정	멱등성 (보통 O)
DELETE	삭제	리소스 삭제	멱등성 O

❓멱등성 (Idempotent)
- 같은 요청 여러 번 보내도 결과가 동일한지 여부

 

3) HTTP 상태코드

• 자주 사용되는 상태코드는 암기

상태 코드	메시지	의미	특징
200	OK	요청 성공	가장 기본 성공 응답
201	Created	리소스 생성 성공	POST 후 생성 시 사용
204	No Content	성공 but 응답 없음	DELETE, UPDATE 후 자주 사용
304	Not Modified	변경 없음	캐시 사용 (클라이언트 캐시 활용)
400	Bad Request	잘못된 요청	파라미터/문법 오류
401	Unauthorized	인증 실패	로그인 안됨 (토큰 없음/잘못됨)
403	Forbidden	권한 없음	로그인 했지만 권한 부족
404	Not Found	리소스 없음	URL or 데이터 없음
405	Method Not Allowed	메서드 불가	GET/POST 잘못 사용
406	Not Acceptable	Accept 미지원	응답 포맷 불일치
415	Unsupported Media Type	Content-Type 미지원	요청 포맷 불일치
500	Internal Server Error	서버 오류	서버 내부 로직 문제

 

4) 데이터 포맷과 콘텐츠 협상

• 클라이언트가 Accept 헤더를 설정하여 원하는 응답 형식을 서버에 알림
• 서버는 Content-Type 헤더로 실제 응답 형식을 명시

# 클라이언트 요청
Accept: application/json

# 서버 응답
Content-Type: application/json

• 주요 미디어 타입

타입	설명
application/json	JSON 형식 (가장 일반적)
application/xml	XML 형식
text/plain	일반 텍스트
multipart/form-data	파일 업로드 시 사용

 

5) 페이징, 필터링, 정렬

필터링: /users?age=30&location=NYC (나이가 30이고 위치가 NYC인 사용자)
페이징: /users?page=2&size=50 (두 번째 페이지, 한 페이지에 50명의 사용자) 
정렬: /users?sort=created_at,desc (회원 가입일의 내림차순으로 정렬)

 

6) API 버전 관리

• URI에 버전을 포함하는 방법이 일반적

/v1/users, /v2/users

• 헤더로 버전을 관리하는 방법도 존재

Accept: application/vnd.myapp.v2+json

 

7) 보안

• HTTPS 사용 : 데이터 암호화로 통신 보안 확보
• 인증(Authentication) : 사용자가 누구인지 확인
  • JWT (JSON Web Token), OAuth 2.0, API Key 방식 등
• 인가(Authorization) : 인증된 사용자가 해당 리소스에 접근 권한이 있는지 확인
  • Role 기반 접근 제어 (RBAC)
• 입력 데이터 검증 : SQL Injection, XSS 등 공격 방지
• Rate Limiting : 과도한 요청 방지 (ex. 1분에 100회 제한)

 

8) 에러처리와 명확한 메시지

• 에러 응답은 일관된 포맷으로 반환

{
  "status": 400,
  "error": "BadRequest",
  "message": "Email format is invalid"
}

 

9) API 문서화

• API 사용법을 문서로 정리하여 개발자 간 소통 원활화
  
  • Swagger (OpenAPI) : 가장 널리 사용, UI로 직접 테스트 가능
  • Postman : API 테스트 및 문서화 동시 가능
  • Redoc : OpenAPI 기반의 깔끔한 문서 생성

 

10) 무상태성 Statelessness

• 서버는 각 요청을 독립적으로 처리하며, 이전 요청의 상태를 유지하지 않음

 

11) 캐시 가능성

• Cache-Control헤더를 사용하여 리소스가 얼마나 오랫동안 캐시될 수 있는지 명시 가능

Cache-Control: max-age=3600 (1시간 동안 캐시 가능