[HTTP 웹]

HTTP 메서드와 URI 디자인

프롯 2025. 6. 10. 01:07

웹 개발이나 API 설계에서 가장 기본적이면서도 중요한 부분이 바로 HTTP 메서드와 URI를 설계하는 방식이다. 이번 글에서 RESTful API 설계의 핵심인 HTTP 메서드 활용법과 좋은 URI 설계 방법을 소개한다.

 

클라이언트에서 서버로 요청을 보낼때, URI에는 리소스 (ex. member/) 만 포함되어 있는 것이 좋다. 그렇다면 이 리소스를 어떻게 하는지에 동사는 어디에 들어가야 할까? 보통은 HTTP 메서드에 그 의미가 함꼐 담긴다.

 

HTTP 메서드의 개념과 종류

HTTP는 클라이언트와 서버 간의 통신을 위한 프로토콜 (규칙) 이다. 요청의 종류에 따라 적절한 HTTP 메서드를 사용해야 서버 개발자와 클라이언트 개발자 간의 소통이 원활해진다. 먼저 HTTP 메서드의 종류는 다음과 같다.

 

주요 메서드 정리

GET 리소스 조회 안전(Safe), 멱등(Idempotent), 캐시 가능
POST 리소스 생성 또는 처리 메시지 바디로 데이터 전송, 캐시 불가
PUT 리소스 전체 수정 또는 생성 멱등, 클라이언트가 URI 지정
PATCH 리소스 일부 수정 멱등 가능 (서버 구현에 따라 다름)
DELETE 리소스 삭제 멱등

기타 메서드

  • HEAD: GET과 유사하지만, 응답 바디 없이 헤더만 반환
  • OPTIONS: 지원하는 메서드 확인
  • TRACE / CONNECT: 디버깅, 프록시용 등 특수 목적

HTTP 메서드 속성 이해

Safe 서버 리소스를 변경하지 않음 GET, HEAD
Idempotent 여러 번 호출해도 같은 결과 GET, PUT, DELETE
Cacheable 응답을 클라이언트에 캐시 가능 GET, HEAD

- get 메서드에도 바디를 넣을 수 있으나, 이를 지원하는 서버가 많지 않아 큰 의미가 없다. 오히려 캐싱을 위해 바디를 넣지 않는것이 좋은 선택.

 

 

클라이언트 → 서버 데이터 전송 방법

HTTP 메서드를 배웠으니, 이번엔 클라이언트에서 서버로 데이터를 전송하는 방법들에 대해 알아보겠다.

 

1. 쿼리 파라미터 (Query String)

  • GET 요청에 사용
  • 검색, 정렬, 필터링 등
GET /members?sort=name&active=true
 
 

2. 메시지 바디

  • POST, PUT, PATCH 요청에 사용
  • 복잡한 객체 데이터, 파일 전송 등에 적합
 
POST /members Content-Type: application/json { "name": "홍길동", "email": "hong@example.com" }

HTML Form 데이터 전송

HTML <form> 태그는 GET과 POST만 지원합니다. 그 외의 메서드는 자바스크립트를 이용한 AJAX 방식에서만 사용 가능하기 때문에, form 태그를 통한 기능 구현에서 URI에 리소스명만 넣기에는 제약이 따른다.

multipart/form-data

  • 주로 이미지, 파일 업로드에 사용
  • boundary로 각 필드 구분
  • 바이너리 데이터도 전송 가능
  • 인코딩이 없으면 전송 중 깨질 수 있음 → 인코딩의 장점은 안전한 전송과 문자셋 보장

RESTful URI 설계 원칙

좋은 URI는 "리소스를 명확하게 식별"해야 하며, "행위는 HTTP 메서드로 구분"한다.

나쁜 예시

POST /createUser GET /getUserInfo

좋은 예시

POST /users GET /users/123

 

URI 설계 유형

문서(Document) 단일 리소스 /users/100
컬렉션(Collection) 리소스 디렉토리, 서버가 관리 /users
스토어(Store) 클라이언트가 리소스 URI 지정 PUT /files/report-2024.pdf
컨트롤러 URI 행위 중심, 메서드로 분리하기 어려운 경우 POST /users/100/deactivate
 

컨트롤러 URI는 REST 원칙에서 벗어나지만, 현실적으로 필요할 수 있음. 제한된 HTML 폼 (GET, POST만 지원) 등 제약을 해결하기 위해 사용됨.

예시로 이해하는 설계 흐름

POST 방식 (컬렉션)

POST /members
  • 서버가 URI(/members/100)를 생성
  • 클라이언트는 URI를 모름 → 서버가 관리

PUT 방식 (스토어)

PUT /files/manual.pdf
  • 클라이언트가 URI 직접 지정
  • 리소스를 덮어쓰기

HTTP API 활용 시 고려 사항

  • 서버 ↔ 서버 통신, 앱, JS AJAX 통신 등 다양하게 사용됨
  • 대부분 application/json 포맷
  • 과거에는 application/x-www-form-urlencoded, text/xml 도 사용됨

마무리

  • URI는 리소스 식별에 집중
  • 행위는 HTTP 메서드로 구분
  • 필요한 경우에는 컨트롤 URI로 유연하게 대응