160. Level 2 - HTTP 메서드의 적절한 분리 사용 (가장 대중적 단계)

핵심 인사이트

본질: 리처드슨 성숙도 모델 (Richardson Maturity Model)의 Level 2는 리소스별 URI (Uniform Resource Identifier)에 더해, HTTP (HyperText Transfer Protocol) 메서드 의미를 작업 종류에 맞게 분리하는 단계다.

가치: GET, POST, PUT, PATCH, DELETE를 올바르게 쓰면 캐시, 재시도, 멱등성 (Idempotency), 상태 코드 해석 같은 웹의 기본 도구를 자연스럽게 활용할 수 있다.

판단 포인트: Level 2는 산업계에서 가장 널리 쓰이는 REST (Representational State Transfer) 기준선이지만, 메서드 이름만 흉내 내고 의미를 어기면 오히려 운영 혼란을 키운다.

Ⅰ. 개요 및 필요성

Level 2는 리소스를 URI로 구분하는 Level 1 위에, 행위 의미를 HTTP 메서드에 맞게 배치한 단계다. 즉 /orders/1001이라는 자원을 두고도 조회는 GET, 전체 수정은 PUT, 부분 수정은 PATCH, 삭제는 DELETE처럼 표준 동사로 의도를 분리한다. 이때 API는 단순한 원격 함수 호출이 아니라, 웹 프로토콜의 의미를 따르는 인터페이스로 바뀌기 시작한다.

이 단계가 필요한 이유는 URI만 자원형이어도 모든 요청을 POST로 처리하면 웹 인프라의 이점을 살리지 못하기 때문이다. 캐시 서버는 GET을 이해하지만 임의의 POST 바디 안 action 필드는 이해하지 못한다. 또한 재시도 정책, 프록시 동작, 상태 코드 해석도 메서드 의미가 분명해야 안정적으로 작동한다.

따라서 Level 2의 본질은 "메서드를 예쁘게 나눈다"가 아니라, 자원 중심 구조 위에 웹 표준의 의미 계층을 얹는다는 데 있다. 그래서 많은 기업이 Level 2를 사실상의 RESTful API 기준선으로 삼는다.

📢 섹션 요약 비유: Level 2는 창구를 업무별로 나누는 데서 한 걸음 더 나아가, 신청서 색깔마다 접수 규칙이 다른 행정 시스템을 만드는 것과 같다.

Ⅱ. 아키텍처 및 핵심 원리

Level 2의 핵심 원리는 같은 리소스 URI라도 메서드에 따라 의미가 달라진다는 점이다. 컬렉션 URI는 생성과 목록 조회를, 개별 리소스 URI는 읽기·수정·삭제를 담당한다. 여기에 상태 코드 (Status Code)를 함께 사용하면, 클라이언트는 응답 본문을 깊게 읽기 전에도 성공과 실패의 종류를 빠르게 해석할 수 있다.

아래 그림은 Level 2가 자원과 메서드를 어떻게 결합하는지 보여준다.

┌────────────────────────────────────────────────────────────────────┐
│              Level 2: 같은 리소스, 다른 HTTP 메서드               │
├────────────────────────────────────────────────────────────────────┤
│ /orders           GET    -> 주문 목록 조회                         │
│ /orders           POST   -> 새 주문 생성                           │
│ /orders/1001      GET    -> 주문 1건 조회                          │
│ /orders/1001      PUT    -> 주문 전체 교체                         │
│ /orders/1001      PATCH  -> 주문 일부 수정                         │
│ /orders/1001      DELETE -> 주문 삭제                              │
│                                                                    │
│ 상태 코드: 200 OK / 201 Created / 204 No Content / 404 Not Found  │
└────────────────────────────────────────────────────────────────────┘

이 그림의 핵심은 URI가 아니라 메서드와 상태 코드 조합이 API 의미를 완성한다는 점이다. 예를 들어 GET은 안전성 (Safe)과 멱등성을 기대할 수 있으므로 캐시와 재시도에 유리하다. PUT과 DELETE도 멱등성이 있어 네트워크 재전송 환경에서 관리가 쉽다. 반면 POST는 보통 멱등하지 않으므로 중복 생성 방지 전략이 필요하다.

메서드	대표 의미	Safe	Idempotent	실무 포인트
`GET`	조회	O	O	캐시와 조회 전용에 적합
`POST`	생성·비멱등 처리	X	X	중복 요청 방지 필요
`PUT`	전체 대체	X	O	자원 전체 표현 일관성 중요
`PATCH`	부분 변경	X	상황별	변경 규칙 명확화 필요
`DELETE`	삭제	X	O	반복 호출 시 동일 결과 유지 고려

즉 Level 2는 URL 규칙만의 문제가 아니라, 클라이언트·서버·캐시·게이트웨이가 모두 이해할 수 있는 공유 의미 체계를 만드는 단계다.

📢 섹션 요약 비유: Level 2는 같은 사무실 문이라도 입구 표지판만 보는 것이 아니라, 접수·수정·폐기 같은 업무 스탬프를 정확히 구분해 처리하는 운영 규칙과 같다.

Ⅲ. 비교 및 연결

Level 2를 이해하려면 Level 1, Level 3와의 경계를 함께 봐야 한다. Level 1은 리소스 URI까지는 도입했지만 메서드 의미가 약해 POST 편중 구조가 남을 수 있다. 반면 Level 3은 여기에 하이퍼미디어 (HATEOAS, Hypermedia as the Engine of Application State)까지 더해, 클라이언트가 링크를 따라 다음 행동을 발견하게 만든다. 따라서 Level 2는 "웹 의미를 본격적으로 쓰기 시작한 단계"라고 정리할 수 있다.

항목	Level 1	Level 2	Level 3
중심 요소	리소스 URI	리소스 URI + HTTP 메서드	메서드 + 하이퍼미디어
메서드 활용	제한적	명확히 분리	명확히 분리
상태 코드 활용	부분적	적극 활용	적극 활용
클라이언트 탐색성	낮음	중간	높음
산업계 채택	높음	매우 높음	제한적

실무적으로 Level 2가 널리 채택되는 이유는 비용 대비 효과가 크기 때문이다. URI, 메서드, 상태 코드만 정리해도 문서화·테스트·모니터링·에러 처리 품질이 크게 개선된다. 반면 Level 3는 장점이 분명해도 클라이언트 구현과 표준화 비용이 더 들어, 모든 조직이 채택하지는 않는다.

또한 Level 2는 오픈 API 명세 (OpenAPI Specification), API 게이트웨이, 프록시 캐시, 서비스 메시 같은 운영 도구와도 잘 맞는다. 이들이 이해하는 기본 문법이 바로 HTTP 메서드와 상태 코드이기 때문이다.

📢 섹션 요약 비유: Level 1이 창구 이름표를 붙인 단계라면, Level 2는 창구마다 어떤 서류를 어떤 절차로 받는지 규칙서까지 붙인 단계다. Level 3는 그다음에 다음 창구로 가는 안내표지까지 자동으로 주는 셈이다.

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

실무에서 Level 2를 잘 적용하려면 메서드 이름보다 자원 모델과 변경 의미를 먼저 명확히 해야 한다. 예를 들어 PUT은 전체 표현을 대체한다는 뜻이므로, 부분 수정에 무심코 쓰면 필드 누락이 데이터 손실로 이어질 수 있다. 반대로 PATCH는 부분 수정에 적합하지만, 패치 문법과 충돌 처리 규칙을 합의하지 않으면 API 일관성이 무너진다.

또한 POST를 만능 액션으로 남발하는 습관을 경계해야 한다. 결제 승인처럼 자원보다는 명령 성격이 강한 경우는 별도 하위 리소스나 작업 리소스로 모델링할 수 있다. 중요한 것은 "동작을 숨기지 않고, 메서드 의미를 깨지 않도록 외부 모델을 설계하는가"이다.

판단 체크리스트

조회 작업이 정말 GET으로 분리되어 캐시와 재시도 이점을 얻는가?
PUT과 PATCH의 의미 차이를 팀이 일관되게 이해하는가?
생성 성공 시 201 Created, 삭제 성공 시 204 No Content 등 상태 코드가 적절한가?
비즈니스 명령형 작업을 자원 모델 안에서 설명 가능하게 표현했는가?

안티패턴

모든 요청을 POST로 보내고 본문 필드로만 행위를 구분하는 것
조회 API인데도 서버 상태를 바꾸어 GET의 안전성을 깨는 것
오류를 모두 200 OK로 응답해 클라이언트 해석 책임을 과도하게 키우는 것
📢 섹션 요약 비유: Level 2 운영은 서류 봉투에 이름만 붙이는 것이 아니라, 접수용·변경용·폐기용 봉투를 실제 규칙대로 쓰게 만드는 행정 통제와 같다.

Ⅴ. 기대효과 및 결론

Level 2의 가장 큰 효과는 API가 웹 표준과 같은 언어로 대화하기 시작한다는 점이다. 클라이언트는 메서드만 봐도 대략적인 의도를 파악할 수 있고, 상태 코드만으로도 오류 유형을 빠르게 분류할 수 있다. 그 결과 테스트 자동화, 문서화, 캐시 전략, 관찰성 (Observability)까지 함께 좋아진다.

하지만 한계도 있다. 메서드와 상태 코드를 잘 쓴다고 해서 곧바로 완전한 REST가 되는 것은 아니다. 다음 상태 전이를 응답 안 링크로 안내하지 않으면, 클라이언트는 여전히 별도 문서에 의존해야 한다. 그래서 Level 2는 매우 실용적이지만, 완전성보다 표준성과 운영 효율을 우선한 타협점으로 보는 것이 맞다.

결론적으로 Level 2는 가장 대중적인 RESTful API의 기준선이다. 핵심은 HTTP 메서드를 나열하는 것이 아니라, 자원·행위·응답 의미를 웹 표준에 맞춰 정렬하는 것이다.

📢 섹션 요약 비유: Level 2는 모두가 같은 행정 용어를 쓰게 만들어, 처음 온 사람도 규칙을 예측할 수 있게 하는 공공 서비스 체계와 같다.

📌 관련 개념 맵

개념	연결 포인트
리처드슨 성숙도 모델	Level 2의 위치를 규정하는 프레임워크
URI	리소스를 식별하는 기본 주소 체계
Safe / Idempotent	메서드 의미를 설계할 때 꼭 확인할 속성
상태 코드 (Status Code)	성공·실패 의미를 표준화하는 응답 수단
HATEOAS	Level 3에서 추가되는 하이퍼미디어 확장 개념

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

Level 0
  (단일 endpoint + action 중심)
    │
    ▼
Level 1
  (리소스별 URI 분리)
    │
    ▼
Level 2
  (HTTP 메서드 · 상태 코드 정착)
    │
    ▼
Level 3
  (HATEOAS 기반 상태 전이 안내)

이 흐름도는 REST 성숙도가 단순 주소 정리에서 끝나지 않고, 웹 프로토콜의 의미와 탐색 가능성까지 확장되는 과정을 보여준다.

👶 어린이 비유 설명

Level 2는 장난감 상자에 이름표만 붙이는 게 아니라, 꺼내기·넣기·고치기 규칙까지 정해 놓는 거예요.
그래서 친구도 어떤 행동을 해야 하는지 쉽게 이해할 수 있어요.
모두가 같은 규칙을 쓰면 실수도 줄고, 정리도 더 쉬워져요.