URI란 무엇인가?

URI (Uniform Resource Identifier)는 웹에서 자원을 고유하게 식별하기 위한 주소임.

URI 설계는 RESTful API의 성공적인 구현을 위한 핵심 요소임.
명확하고 일관된 URI 설계를 통해 자원을 쉽게 식별하고 서비스의 신뢰성과 사용성을 높일 수 있음.

---

URI의 역할

우리가 웹 서비스를 이용할 때, 서버와 클라이언트는 다양한 데이터를 주고받음.
이 데이터는 HTML, CSS, 이미지, 오디오, 비디오 등으로 구성되며, 이를 자원(Resource)이라고 부름.
URI는 이러한 자원 각각을 명확히 식별하여 접근할 수 있도록 만들어 줌.

---

자원 식별의 중요성

REST에서 URI는 특정 자원을 식별하는 데 필수적인 요소임.

• 자원을 명확히 식별하지 못하면, 서버는 어떤 데이터를 제공해야 하는지 알 수 없음.
• 예시:
  • 단순히 "좌석"만으로는 어떤 좌석을 선택했는지 알 수 없음.
  • 하지만 H열/11과 같은 형식을 사용하면 11번 좌석을 명확히 식별할 수 있음.
    이는 URI가 자원을 명확히 정의하고 식별하도록 돕는 역할임.

좌석 예매 시스템과 유사

URI: /seats/h열/11  
의미: H열 11번 좌석

---

URI 설계의 원칙

잘 설계된 URI는 자원의 형식과 식별 방식을 명확히 보여줌.
URI 설계에서 고려해야 할 주요 요소는 다음과 같음.

원칙	설명
자원의 명확성	URI만 보고도 어떤 자원을 가리키는지 쉽게 알 수 있어야 함.
단수형과 복수형 사용	자원이 한 개인지 여러 개인지를 명확히 구분해야 함.
계층 구조 활용	자원의 위치를 계층적으로 나타내는 구조가 직관적임.
일관성 유지	URI 설계 방식은 서비스 전체에서 일관되게 유지되어야 함.
예측 가능성	URI를 통해 관련된 API 작업을 쉽게 예상할 수 있어야 함.

---

URI 설계의 예시

1. 자원의 명확성

• 잘못된 URI:
  /seats

  • 좌석이 너무 포괄적으로 표현되어 특정 자원을 식별할 수 없음.

• 잘 설계된 URI:
  /seats/hr/11

  • HR 상영관의 11번 좌석을 명확히 식별.

2. 단수형과 복수형 사용

• 단수형: /user/1 (특정 사용자 1명)
• 복수형: /users (사용자 목록 전체)

3. 계층 구조 활용

• 잘못된 URI: /tickets_and_seats

  • 자원 간의 계층 구조를 명확히 표현하지 않음.

• 잘 설계된 URI:
  /theaters/hr/seats/11/tickets

  • 상영관 → 좌석 → 티켓의 계층적 구조를 명확히 표현.

---

URI 설계가 중요한 이유

1. 가독성: 사용자가 URI만 보고 자원을 쉽게 이해할 수 있음.
2. 유지보수성: 개발자와 사용자 모두 쉽게 예측 가능하고 확장 가능.
3. 예측 가능성: URI가 일관성 있게 설계되면, 다른 API 작업도 쉽게 유추할 수 있음.

---

🎯 URI 설계의 핵심 원칙

• 자원을 명확하게 식별할 수 있어야 함.
• 자원의 위치와 종류를 직관적으로 파악할 수 있어야 함.

REST API URI 설계 핵심 가이드

1. 기본 규칙

규칙	설명	✅ 올바른 예시	❌ 잘못된 예시
명사 사용	자원을 나타내는 명사로 표현	/members	/get-member-list
복수형/단수형	목록은 복수형, 단일 자원은 단수형	/members(목록) /members/1(단일)	-
계층 구조	슬래시(/)로 계층 관계 표현	/articles/1/comments	-
소문자 사용	전체 URI는 소문자로 작성	/articles/top-voted	/articles/topVoted
띄어쓰기	하이픈(-)으로 표현	/user-profiles	/user_profiles

2. 추가 규칙

규칙	✅ 올바른 방식	❌ 잘못된 방식
마지막 슬래시	/articles/1	/articles/1/
파일 확장자	/articles	/articles.json
동작 표현	DELETE /members/1 PUT /members/2	/members/1/delete /members/2/update
필터링	/articles?category=tech&sort=latest	/get-tech-articles-sorted

3. 계층 구조 예시

/articles                    # 전체 게시글
/articles/1                  # 1번 게시글
/articles/1/comments         # 1번 게시글의 댓글들
/articles/1/comments/2       # 1번 게시글의 2번 댓글

4. 필터링 예시

/articles?status=published   # 발행된 게시글
/members?role=admin&active=true   # 활성 관리자
/products?category=electronics&price=asc   # 전자제품 가격순 정렬