HTTP 메서드 활용
회원 관리 API 설계 (Post 기반 등록)
HTTP API를 사용하여 회원 관리용 API를 개발한다고 가정해봅시다.
이때 URI와 HTTP 메서드인 GET, POST, PUT, DELETE를 어떻게 사용해야 하는지 살펴보겠습니다.
리소스 식별과 HTTP 메서드의 역할
- 리소스 식별: URI는 리소스를 식별해야 합니다.
“조회하다”, “삭제하다”와 같은 동작을 URI에 포함시키지 말고,
이러한 동작은 HTTP 메서드를 통해 표현해야 합니다. - HTTP 메서드:
- GET: 리소스 조회
- POST: 리소스 생성
- PUT: 리소스 생성 또는 전체 업데이트
- PATCH: 리소스 부분 업데이트
- DELETE: 리소스 삭제
회원 목록 조회
- URI: /members
- HTTP 메서드: GET
- 설명: 회원 전체 목록을 조회합니다.
회원이 많을 경우, 쿼리 파라미터를 사용하여 검색어나 정렬 조건을 추가할 수 있습니다. - 예시:
GET /members?name=John&sort=age
회원 등록 (생성)
- URI: /members
- HTTP 메서드: POST
- 설명: 새로운 회원을 등록합니다.
클라이언트는 회원 정보를 서버에 전송하고,
서버는 새로운 리소스의 URI를 생성하여 반환합니다. 예시:
POST /members Content-Type: application/json { “username”: “young”, “age”: 20 }
서버 응답:
HTTP/1.1 201 Created Location: /members/100
회원 조회 (단건 조회)
- URI: /members/{id}
- HTTP 메서드: GET
- 설명: 특정 회원의 상세 정보를 조회합니다.
예시:
GET /members/100
회원 삭제
- URI: /members/{id}
- HTTP 메서드: DELETE
- 설명: 특정 회원을 삭제합니다.
예시:
DELETE /members/100
회원 수정
- URI: /members/{id}
- HTTP 메서드: PATCH 또는 PUT
- 설명:
- PATCH: 회원 정보의 일부를 수정합니다.
- PUT: 회원 정보를 전체 업데이트합니다. 기존 정보를 완전히 대체합니다.
예시:
PATCH /members/100 Content-Type: application/json { “age”: 25 }
PUT /members/100 Content-Type: application/json
{ “username”: “young”, “age”: 25, “email”: “young@example.com” }
컬렉션(Collection) 패턴
- 설명: 서버가 리소스의 URI를 생성하고 관리하는 방식입니다.
- 특징:
- 클라이언트는 등록될 리소스의 URI를 모릅니다.
- 서버가 새로운 리소스의 URI를 생성하여 반환합니다.
- 예시: 회원 등록 시 /members에 POST 요청을 보내면, 서버가 새로운 회원의 URI를 생성하여 응답합니다.
확인 문제
- 질문: 회원 정보를 부분적으로 수정할 때 적합한 HTTP 메서드는 무엇인가요?
- 답변: PATCH
- 질문: 클라이언트가 리소스의 URI를 모르는 상태에서 서버에 리소스 생성을 요청할 때 사용하는 HTTP 메서드는 무엇인가요?
- 답변: POST
파일 관리 시스템 API 설계 (Put 기반 등록)
이번에는 파일 관리 시스템을 예시로, PUT 기반으로 리소스를 등록하는 방법을 살펴보겠습니다.
클라이언트가 리소스 URI를 지정하는 경우
- 리소스 등록: 클라이언트가 등록될 리소스의 URI를 알고 있으며, 직접 지정하여 서버에 요청합니다.
- HTTP 메서드: PUT
파일 업로드 (생성 또는 업데이트)
- URI: /files/{filename}
- HTTP 메서드: PUT
- 설명:
- 클라이언트는 업로드할 파일의 이름을 알고 있으며, 해당 파일을 서버에 저장합니다.
- 파일이 이미 존재하면 기존 파일을 대체합니다.
예시:
PUT /files/star.jpg Content-Type: image/jpeg (파일 내용)
파일 조회
- URI: /files/{filename}
- HTTP 메서드: GET
- 설명: 특정 파일을 다운로드합니다.
예시:
GET /files/star.jpg
파일 삭제
- URI: /files/{filename}
- HTTP 메서드: DELETE
- 설명: 특정 파일을 삭제합니다.
예시:
DELETE /files/star.jpg
스토어(Store) 패턴
- 설명: 클라이언트가 리소스의 URI를 알고 관리하는 방식입니다.
- 특징:
- 클라이언트가 리소스의 URI를 지정하여 요청합니다.
- 서버는 클라이언트가 지정한 URI에 리소스를 저장하거나 업데이트합니다.
- 예시: 파일 업로드 시 클라이언트가 /files/star.jpg에 PUT 요청을 보냅니다.
확인 문제
- 질문: 클라이언트가 리소스의 URI를 직접 지정하여 서버에 리소스를 저장하는 패턴은 무엇인가요?
- 답변: 스토어(Store) 패턴
- 질문: 기존 파일을 새로운 파일로 완전히 대체할 때 사용하는 HTTP 메서드는 무엇인가요?
- 답변: PUT
HTML Form을 이용한 API 설계
HTML 폼을 사용하여 API를 설계할 때는 GET과 POST 메서드만 사용할 수 있습니다. 따라서 제한된 메서드 내에서 URI와 동작을 설계해야 합니다.
회원 등록 폼
- URI: /members/new
- HTTP 메서드:
- 폼 조회: GET
- 폼 전송: POST
- 설명:
- GET /members/new: 회원 등록 폼을 제공합니다.
- POST /members/new: 폼 데이터를 전송하여 새로운 회원을 등록합니다.
예시:
GET /members/new
POST /members/new Content-Type: application/x-www-form-urlencoded username=young&age=20
회원 수정 폼
- URI: /members/{id}/edit
- HTTP 메서드:
- 폼 조회: GET
- 폼 전송: POST
- 설명:
- GET /members/100/edit: 회원 수정 폼을 제공합니다.
- POST /members/100/edit: 폼 데이터를 전송하여 회원 정보를 수정합니다.
예시:
GET /members/100/edit
POST /members/100/edit Content-Type: application/x-www-form-urlencoded age=25
회원 삭제
- URI: /members/{id}/delete
- HTTP 메서드: POST
- 설명: 회원을 삭제합니다. DELETE 메서드를 사용할 수 없으므로 POST를 사용하고, URI에 동사를 포함합니다.
예시:
POST /members/100/delete
컨트롤 URI의 사용
- 설명:
- HTML 폼의 제한으로 인해 동사(행위)를 URI에 포함시켜야 하는 경우가 있습니다.
- 이러한 URI를 컨트롤러 URI 또는 컨트롤 URI라고 합니다.
- 동사를 사용하여 리소스의 상태나 동작을 명시합니다.
- 예시:
- /members/new
- /members/{id}/edit
- /members/{id}/delete
확인 문제
- 질문: HTML 폼에서 DELETE 메서드를 사용할 수 없을 때, 회원 삭제를 위해 어떻게 URI를 설계하나요?
- 답변: POST 메서드를 사용하고, URI에 동사인 /delete를 포함하여 /members/{id}/delete로 요청합니다.
- 질문: 컨트롤러 URI를 사용할 때 URI에 포함되는 것은 무엇인가요?
- 답변: 동사(행위)
컨트롤 URI의 필요성
실제 개발 환경에서는 HTTP 메서드만으로 모든 동작을 표현하기 어려운 경우가 많습니다.
이때 컨트롤 URI를 사용하여 추가적인 동작을 명시합니다.
컨트롤 URI의 특징
- 동사 사용: URI에 동사를 포함하여 특정 행위를 표현합니다.
- 필요성:
- HTTP 메서드로 표현하기 어려운 복잡한 동작을 처리하기 위해 필요합니다.
- 예를 들어, 주문 상태를 변경하거나 특정 프로세스를 실행하는 경우입니다.
예시
- 주문 배송 시작:
- URI: /orders/{id}/deliver
- HTTP 메서드: POST
- 설명: 주문의 배송을 시작합니다.
- 회원 비밀번호 초기화:
- URI: /members/{id}/reset-password
- HTTP 메서드: POST
- 설명: 회원의 비밀번호를 초기화합니다.
확인 문제
- 질문: 컨트롤 URI를 사용할 때 URI에 동사를 포함시키는 이유는 무엇인가요?
- 답변: HTTP 메서드만으로 표현하기 어려운 특정 동작이나 프로세스를 명시하기 위해서입니다.
- 질문: 컨트롤 URI의 사용을 최소화하기 위해 우선적으로 고려해야 할 것은 무엇인가요?
- 답변: 리소스 중심의 URI 설계와 HTTP 메서드의 적절한 사용으로 최대한 동작을 표현하고, 필요한 경우에만 컨트롤 URI를 사용합니다.
URI 설계 개념 정리 및 팁
URI 설계 시 참고하면 좋은 개념들을 정리하겠습니다. 이는 공식적인 표준은 아니지만, 많은 개발자들이 좋은 실천 사례로 활용하고 있는 패턴입니다.
주요 개념
- 문서(Document)
- 설명: 단일 개념 또는 객체 인스턴스입니다.
- 예시:
- /members/100
- /files/star.jpg
- 컬렉션(Collection)
- 설명: 서버가 관리하는 리소스 디렉토리로, 서버가 리소스의 URI를 생성하고 관리합니다.
- 예시:
- /members
- /orders
- 스토어(Store)
- 설명: 클라이언트가 관리하는 리소스 저장소로, 클라이언트가 리소스의 URI를 알고 지정합니다.
- 예시:
- /files/{filename}
- 컨트롤러(Controller)
- 설명: 리소스만으로 표현하기 어려운 추가적인 프로세스나 동작을 실행할 때 사용합니다. URI에 동사를 포함합니다.
- 예시:
- /members/{id}/activate
- /orders/{id}/cancel
URI 설계 팁
- 리소스 중심의 URI 설계: 리소스를 명사로 표현하고, 행위는 HTTP 메서드로 표현합니다.
- 복수형 사용: 컬렉션을 나타낼 때는 복수형을 사용합니다. 예: /members, /orders
- 계층 구조 활용: 리소스 간의 관계를 URI 계층 구조로 표현합니다.
- 컨트롤 URI 최소화: 가능하면 HTTP 메서드로 동작을 표현하고, 필요한 경우에만 컨트롤 URI를 사용합니다.
확인 문제
- 질문: 서버가 리소스의 URI를 생성하고 관리하는 패턴은 무엇인가요?
- 답변: 컬렉션(Collection) 패턴
- 질문: 리소스 중심의 URI 설계에서 행위는 어떻게 표현하나요?
- 답변: HTTP 메서드를 사용하여 표현합니다.