REST API 설계

---

🌐 REST API 설계란?

정의

REST API 설계는 리소스를 명확하게 표현하고 HTTP Method를 적절하게 사용하도록 API를 구성하는 방식이다. URI, 상태 코드, 요청/응답 형식을 일관되게 정리하는 것이 핵심이다.

🎯 설계 원칙

• URI는 명사 중심으로 만든다.
• 동작은 HTTP Method로 표현한다.
• 리소스 구조를 일관되게 유지한다.
• 응답 형식을 통일한다.
• 상태 코드를 적절히 사용한다.

포인트

REST API는 URL에 행동을 넣는 방식보다 리소스와 메서드로 의미를 표현하는 방식이 더 자연스럽다.

🧱 URI 설계 규칙

좋은 예

GET /users
GET /users/1
POST /users
PUT /users/1
DELETE /users/1

피해야 할 예

GET /getUser
POST /createUser
POST /deleteUser

• URI에는 동사보다 명사를 우선 사용한다.
• 계층 구조는 관련 리소스를 드러내는 데만 사용한다.
• 너무 깊은 URI는 피하는 것이 좋다.

🔄 HTTP Method 사용 기준

Method	사용 예
GET	조회
POST	생성, 처리 요청
PUT	전체 수정
PATCH	일부 수정
DELETE	삭제

📦 응답 설계

성공 응답 예시

{
  "status": 200,
  "message": "success",
  "data": {}
}

에러 응답 예시

{
  "status": 400,
  "message": "Bad Request",
  "errorCode": "VALIDATION_ERROR",
  "data": null
}

정리

응답은 성공/실패 모두 같은 규칙으로 표현하는 것이 좋다. 프론트엔드와 협업할 때 특히 중요하다.

🔢 자주 쓰는 상태 코드

상태 코드	설명
200	성공
201	생성 성공
204	본문 없는 성공
400	잘못된 요청
401	인증 필요
403	권한 없음
404	리소스 없음
409	충돌
500	서버 오류

🧩 설계 시 고려사항

• 페이지네이션이 필요한가
• 검색과 필터링이 필요한가
• 정렬 기준이 필요한가
• 인증과 인가를 어떻게 적용할 것인가
• 버전 관리를 어떻게 할 것인가

페이지네이션 예시

GET /users?page=1&size=20

필터링 예시

GET /users?status=ACTIVE

버전 관리 예시

/api/v1/users
/api/v2/users

🔐 인증과 인가

• JWT는 세션보다 확장성이 좋은 경우가 많다.
• OAuth2는 외부 서비스 연동이나 권한 위임에 적합하다.
• 민감한 API는 인증과 인가를 분리해서 설계해야 한다.

⚠️ 주의할 점

• URI에 행동을 과하게 넣지 않는다.
• 상태 코드와 응답 메시지를 섞어 쓰지 않는다.
• 실패 응답의 형식을 통일한다.
• 문서화 없이 설계하면 유지보수가 어려워진다.

[!important] 정리 REST API 설계는 리소스 중심 URI, 명확한 HTTP Method, 일관된 응답 형식이 핵심이다. API가 많아질수록 규칙을 초기에 잘 잡아두는 것이 중요하다.

---

연결문서

• Restful
• HTTP Method
• HTTP Request
• HTTP Response
• JWT
• OAuth2