159. Level 1 - 리소스별 고유 URI 할당

핵심 인사이트

본질: 리처드슨 성숙도 모델 (Richardson Maturity Model)의 Level 1은 REST (Representational State Transfer) 설계에서 애플리케이션 프로그래밍 인터페이스 (API, Application Programming Interface)가 다루는 대상을 행위가 아니라 리소스 (Resource) 중심으로 식별하기 시작한 단계다.

가치: orders, customers, payments처럼 자원별 URI (Uniform Resource Identifier)를 분리하면 시스템 구조가 드러나고, 이후 HTTP (HyperText Transfer Protocol) 메서드와 상태 코드 정비로 확장할 기반이 생긴다.

판단 포인트: Level 1은 REST의 출발점이지만 아직 완성형은 아니며, URI만 명사형으로 바꾸고 모든 작업을 POST로 처리하면 설계 품질은 절반만 개선된다.

Ⅰ. 개요 및 필요성

Level 1은 단일 엔드포인트에 모든 작업을 몰아넣는 Level 0에서 한 단계 올라가, 자원마다 고유한 URI를 부여하는 단계다. 여기서 중요한 변화는 API의 중심 질문이 "무슨 함수를 호출할까"에서 "어떤 자원을 다룰까"로 바뀐다는 점이다. 즉 주문, 사용자, 상품 같은 비즈니스 대상을 외부 인터페이스에 드러내기 시작한다.

이 변화가 필요한 이유는 단일 URI 구조가 시스템 의미를 숨기기 때문이다. POST /api와 요청 바디 안의 action만으로는, 외부 소비자가 어떤 자원을 조작하는지 직관적으로 이해하기 어렵다. 반면 POST /orders, POST /customers, POST /shipments처럼 나누면 API의 도메인 경계가 훨씬 선명해진다.

Level 1은 그래서 단순한 URL 정리 작업이 아니다. API를 비즈니스 자산 단위로 재구성하는 첫 단계이며, 이후 메서드 의미 분리와 상태 코드 설계를 가능하게 만드는 기초 공사다.

📢 섹션 요약 비유: Level 1은 모든 민원을 건물 입구 한 곳에서 받던 방식을, 여권 창구·세무 창구·복지 창구처럼 업무 대상별 창구로 나누는 일과 같다.

Ⅱ. 아키텍처 및 핵심 원리

Level 1의 핵심 원리는 "리소스를 URI로 식별한다"는 것이다. 보통 컬렉션과 개별 항목을 구분해 /orders와 /orders/1001처럼 설계한다. 아직 Level 2처럼 메서드 의미를 충분히 살리지 못할 수는 있지만, 적어도 API 외형만 봐도 어떤 자원을 다루는지는 드러난다.

아래 그림은 Level 0에서 Level 1로 넘어갈 때 무엇이 달라지는지 보여준다.

┌────────────────────────────────────────────────────────────────────┐
│            Level 0 → Level 1 전환 시 의미 변화                    │
├────────────────────────────────────────────────────────────────────┤
│ [Level 0]                                                         │
│ POST /api                                                         │
│ { action: "createOrder", customerId: 7 }                         │
│ POST /api                                                         │
│ { action: "cancelOrder", orderId: 1001 }                         │
│                                                                    │
│ [Level 1]                                                         │
│ POST /orders                -> 주문 컬렉션에 생성 요청             │
│ POST /orders/1001/cancel    -> 아직 메서드는 미성숙할 수 있음      │
│ GET  /orders/1001?          -> 이상적이지만 Level 2에서 본격 정착  │
│                                                                    │
│ 핵심 변화: "행위 이름"보다 "대상 자원"이 URI에 드러남           │
└────────────────────────────────────────────────────────────────────┘

이 단계에서 설계자는 보통 컬렉션 URI, 개별 리소스 URI, 하위 리소스 URI를 정의한다. 예를 들어 고객과 주문 관계를 /customers/7/orders처럼 표현할 수 있다. 이 구조는 API 문서화, 라우팅, 권한 모델링, 로그 분석에 직접 도움이 된다. 왜냐하면 요청 경로만 보아도 시스템이 어떤 도메인 객체를 만졌는지 알 수 있기 때문이다.

URI 유형	예시	의미
컬렉션	`/orders`	주문 자원들의 집합
단일 리소스	`/orders/1001`	특정 주문 1건
하위 리소스	`/customers/7/orders`	고객 7에 속한 주문 목록
상태 전이 URI	`/orders/1001/cancel`	Level 1에서 자주 보이는 절충형 표현

다만 Level 1은 URI 설계만 성숙해졌을 뿐, HTTP 메서드·상태 코드·하이퍼미디어 활용은 아직 부족할 수 있다. 그래서 이 단계는 완성이라기보다, API 의미를 바디 밖으로 끌어내기 시작한 상태라고 보는 것이 맞다.

📢 섹션 요약 비유: Level 1은 상자 겉면에 내용물을 적어 두는 단계와 같다. 아직 여는 방법까지 표준화된 것은 아니지만, 최소한 안에 무엇이 있는지는 밖에서 알 수 있다.

Ⅲ. 비교 및 연결

Level 1의 위치를 이해하려면 Level 0과 Level 2 사이에 놓고 봐야 한다. Level 0은 단일 URI와 액션 중심 메시지로 이루어진 RPC (Remote Procedure Call) 스타일이다. Level 1은 자원을 URI로 분리하지만, 메서드 사용은 아직 거칠 수 있다. Level 2는 여기에 GET, POST, PUT, PATCH, DELETE와 상태 코드를 일관되게 도입한다.

항목	Level 0	Level 1	Level 2
URI 구조	단일 엔드포인트	자원별 분리	자원별 분리
중심 사고	작업 호출	자원 식별	자원 식별 + 표준 행위
메서드 활용	POST 중심	제한적 또는 혼합	명확히 분리
상태 코드 활용	약함	약함 또는 부분적	강함
설계 가독성	낮음	중간	높음

실무적으로 Level 1이 중요한 이유는, RESTful 설계의 모든 이점이 여기서 바로 완성되지는 않더라도 자원 경계를 명확히 드러내기 때문이다. 도메인 주도 설계 (DDD, Domain-Driven Design) 관점에서도 orders, invoices, members처럼 경계가 드러나는 URI는 서비스 책임을 정리하는 데 도움이 된다. 반면 doCancelOrder, processInvoice 같은 동사 중심 URI는 내부 서비스 함수를 외부에 그대로 노출하는 경향이 강하다.

즉 Level 1은 REST의 완성형이 아니라, RPC 사고방식에서 자원 중심 사고방식으로 넘어가는 다리다. 이 다리를 건너야 이후 Level 2, Level 3 논의도 의미를 가진다.

📢 섹션 요약 비유: Level 0이 모든 요청을 한 사람에게 구두로 전달하는 방식이라면, Level 1은 업무별 서류함이 생긴 상태이고, Level 2는 각 서류함마다 접수 규칙까지 붙은 상태다.

Ⅳ. 실무 적용 및 기술사 판단

실무에서는 레거시 RPC API를 바로 Level 2나 Level 3로 끌어올리기 어려운 경우가 많다. 이때 가장 현실적인 첫 단계가 Level 1이다. 우선 자원 경계를 분리해 URI 체계를 정리하면, 라우팅 규칙과 문서 구조, 권한 정책, 로그 분석 축이 단번에 선명해진다. 이후 메서드와 상태 코드는 점진적으로 정리할 수 있다.

하지만 Level 1에서 멈추면 반쪽짜리 개선에 머물 수 있다. URI는 자원형인데 모든 작업을 POST로만 받고, 실패도 전부 200 OK로 돌려주면 웹 인프라가 주는 이점을 충분히 누리지 못한다. 따라서 실무 판단은 "URI 분리만으로 끝낼 것인가"가 아니라, "Level 1을 발판으로 Level 2까지 갈 계획이 있는가"를 함께 봐야 한다.

판단 체크리스트

API 경로가 명사형 자원 중심으로 설계되었는가?
컬렉션과 개별 리소스 URI가 구분되는가?
동사형 URI가 도메인 구조를 흐리지 않는가?
다음 단계로 HTTP 메서드와 상태 코드 정비 계획이 있는가?

안티패턴

URI만 /orders로 바꾸고 실제 의미는 여전히 action 필드에 숨겨 두는 것
/getOrders, /createOrder, /deleteOrder 같은 동사형 경로를 리소스 설계라고 착각하는 것
Level 1 상태를 REST 완성형처럼 홍보하는 것
📢 섹션 요약 비유: Level 1 도입은 사무실 서류함 이름을 붙이는 것과 같다. 이름표만 붙이고 여전히 모든 일을 같은 방식으로 처리하면 정리는 되었지만 운영 혁신은 아직 덜 끝난 셈이다.

Ⅴ. 기대효과 및 결론

Level 1의 기대효과는 인터페이스 의미가 밖으로 드러난다는 점이다. API를 처음 보는 사람도 URI만 보고 어떤 자원이 있는지 짐작할 수 있고, 서비스 경계와 문서 구조도 더 안정된다. 이는 장기적으로 API 거버넌스, 버전 관리, 권한 정책 정비에 좋은 기반이 된다.

반면 한계도 명확하다. URI가 자원 중심이어도 메서드와 상태 코드가 미성숙하면 캐시, 멱등성, 표준 오류 처리 같은 웹 아키텍처 이점을 충분히 살리기 어렵다. 그래서 Level 1은 목표라기보다 REST 설계가 시작되었다는 신호로 이해해야 한다.

결론적으로 이 개념의 핵심은 "자원에게 이름을 붙여 외부에 드러낸다"는 데 있다. REST의 첫 성숙은 결국 함수 호출을 예쁘게 포장하는 것이 아니라, 시스템의 대상을 리소스 단위로 재구성하는 데서 출발한다.

📢 섹션 요약 비유: Level 1은 도시 지도에 건물 이름을 적기 시작한 단계와 같다. 아직 교통법규까지 완성된 것은 아니지만, 어디가 무엇인지는 비로소 보이기 시작한다.

📌 관련 개념 맵

개념	연결 포인트
리처드슨 성숙도 모델	Level 1이 속한 REST 성숙도 프레임워크
URI	리소스를 외부에 식별시키는 핵심 수단
컬렉션/리소스	`/orders`와 `/orders/1001` 같은 구조의 기본 단위
HTTP 메서드	Level 2에서 본격적으로 의미가 강화되는 요소
RPC 스타일 API	Level 1이 벗어나려는 출발점

📈 관련 키워드 및 발전 흐름도

Level 0
  (단일 URI + action 중심)
    │
    ▼
Level 1
  (리소스별 고유 URI)
    │
    ├─ 컬렉션/개별 리소스 구분
    ├─ 도메인 경계 노출
    └─ 문서화 · 라우팅 명확화
    ▼
Level 2
  (HTTP 메서드 · 상태 코드 정착)

이 흐름도는 API 설계가 함수 호출 중심에서 자원 중심 구조로 이동한 뒤, 다시 표준 웹 의미를 채워 넣는 순서를 보여준다.

👶 어린이를 위한 3줄 비유 설명

Level 1은 모든 물건을 한 상자에 넣지 않고, 장난감 상자·책 상자처럼 이름표를 붙여 나누는 거예요.
그래서 어디에 무엇이 있는지 훨씬 쉽게 알 수 있어요.
하지만 상자를 여는 규칙까지 똑같이 정리하려면 다음 단계가 더 필요해요.