RESTful API 디자인 가이드

moon.kick·2025년 4월 21일

좋아, 벨로그 타고 들어간 게 RESTful API 관련 디자인 가이드라면, 아마도 REST API를 잘 설계하는 법에 대한 글일 거야. 이건 백엔드 개발자든, 프론트엔드 개발자든, API를 사용하는 모든 개발자에게 꼭 필요한 개념이지. 여기서 하나하나 쉽게 정리해줄게!

✅ RESTful API 디자인 가이드란?

RESTful API 디자인 가이드는,
"URL은 어떻게 만들고",
"요청 방식(method)은 어떤 걸 쓰고",
"응답은 어떤 구조로 보내야 하고",
"에러는 어떻게 처리할지"
등을 일관되게 정리해 둔 규칙 세트야.

REST는 Representational State Transfer의 약자로,
웹 자원을 HTTP로 주고받는 아키텍처 스타일이야.

💡 기본 구성 개념 정리

1. 📦 리소스(Resource)는 명사로 표현

URL에는 동사가 아니라 명사를 써야 해.

잘못된 예	올바른 예
`/getUser`	`/users/1`
`/createPost`	`/posts`

REST에서는 리소스를 URI로 표현하고,
그 리소스를 다루는 행위는 HTTP 메서드로 구분해.

2. 🔨 HTTP 메서드 사용법

메서드	설명	예시
`GET`	조회	`GET /users`
`POST`	생성	`POST /users`
`PUT`	전체 수정	`PUT /users/1`
`PATCH`	일부 수정	`PATCH /users/1`
`DELETE`	삭제	`DELETE /users/1`

3. 🧭 URL 구조 예시 (계층 구조)

모든 리소스는 복수형으로 작성:
- /users, /products, /comments
하위 자원은 계층 구조로 연결:
- /users/1/posts/5/comments

4. 🔁 쿼리 파라미터는 조건 필터링용

GET /users?age=20&gender=female

나이 20세, 성별 여성인 유저 필터링

5. 📩 응답 구조 예시 (JSON 통일)

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Kim",
    "email": "kim@example.com"
  }
}

에러일 경우:

{
  "status": "error",
  "message": "User not found"
}

6. 🚨 상태코드 (HTTP Status)

코드	의미	상황 예시
200	OK	성공
201	Created	생성 성공
204	No Content	삭제 성공 (응답 없음)
400	Bad Request	잘못된 요청
401	Unauthorized	인증 실패
403	Forbidden	권한 없음
404	Not Found	리소스 없음
500	Internal Server Error	서버 오류

7. 📚 참고로 자주 쓰는 URL 예시

동작	메서드	URL
회원 목록 조회	GET	`/users`
특정 회원 조회	GET	`/users/1`
회원 등록	POST	`/users`
회원 수정	PUT/PATCH	`/users/1`
회원 삭제	DELETE	`/users/1`