6회차: ASP.NET Core Web API & 네이밍 규칙

✅ 기본 RESTful 네이밍 규칙 복습

목적 예시 설명

전체 목록 조회	GET /todos	할 일 전체 목록
단일 항목 조회	GET /todos/123	ID가 123인 항목
생성	POST /todos	새 항목 생성
수정	PUT /todos/123	항목 전체 수정
삭제	DELETE /todos/123	항목 삭제

---

✅ 2단계 URL 구조 (두 단)

🔸 대표적인 경우: 상위-하위 관계

예: 할 일(Todo)에 속한 댓글(Comment)

작업 URL 예시 설명

특정 Todo의 댓글 목록	GET /todos/123/comments	Todo 123에 속한 댓글들
특정 댓글 조회	GET /todos/123/comments/7	Todo 123의 댓글 ID 7
댓글 생성	POST /todos/123/comments	Todo 123에 댓글 추가
댓글 수정	PUT /todos/123/comments/7	댓글 수정
댓글 삭제	DELETE /todos/123/comments/7	댓글 삭제

✅ 2단 URI는 “하위 리소스가 상위 리소스에 종속”된 경우에만 사용합니다.

---

🧠 네이밍 시 유의점

원칙 설명

✅ 복수형 사용	리소스명은 보통 복수형 (todos, comments)
✅ 소문자, 하이픈	kebab-case 또는 소문자 사용: user-posts, task-logs
❌ 동사 사용 금지	/getUsers, /createComment 대신 /users, /comments
✅ 리소스 계층 표현	/users/123/posts → "123번 유저의 게시물"처럼 자연스럽게

---

📦 예시: 다양한 2단 리소스 구조

자원 2단 URI 예시 의미

블로그 글의 댓글	/posts/55/comments	글 55번의 댓글들
유저의 주문	/users/42/orders	유저 42의 주문 목록
게시판의 게시물	/boards/10/posts	게시판 10번의 글
카테고리의 상품	/categories/3/products	카테고리 3번에 속한 상품

---

✅ 한 줄 요약

RESTful API에서 2단 URI는
/상위자원/{id}/하위자원 형태로 표현하며,
**자원 간 관계(포함, 종속, 소속)**를 나타낼 때 사용합니다.

 

---

✅ 페이지네이션이 필요한 todos API 예시

🔸 기본 형태

GET /todos?page=1&size=20

파라미터 의미

page	현재 페이지 번호 (1부터 시작)
size	한 페이지에 가져올 항목 수

➡️ 이 방식은 REST의 리소스 구조를 해치지 않고,
정렬/검색/필터링과도 함께 조합이 가능합니다.

---

✅ 응답 예시 (JSON)

{
  "data": [
    { "id": 1, "title": "할 일 1", "isCompleted": false },
    { "id": 2, "title": "할 일 2", "isCompleted": true }
  ],
  "pagination": {
    "page": 1,
    "size": 2,
    "totalItems": 35,
    "totalPages": 18
  }
}

• data: 실제 데이터 배열
• pagination: 현재 페이지 상태를 표현하는 메타데이터

✅ 이런 구조를 Client와 Backend가 명확히 약속하면,
무한 스크롤, 페이지 버튼 등도 쉽게 구현할 수 있어요.

---

✅ 잘못된 방식은?

GET /todos/page/2/size/20  ❌

• URI에서 페이지 번호를 리소스처럼 취급하면 RESTful하지 않음
• 페이지는 자원이 아니라 조회 방법의 조건이므로,
  쿼리 스트링으로 전달하는 게 맞습니다

---

🧠 추가 팁: 더 나아간 페이지네이션

방식 예시 특징

offset 기반	?page=2&size=10	간단하고 일반적
cursor 기반	?after=todo_id_100&limit=20	대규모 데이터에 더 효율적 (무한스크롤 최적화)

---

✅ 한 줄 요약

GET /todos?page=1&size=20처럼
페이지 번호는 URL 경로가 아니라, 쿼리 파라미터로 표현하는 것이 RESTful한 방식입니다.