HTTP 메소드와 API 설계

API URI 설계

• 가장 중요한 것은 리소스를 식별하는 것
• 리소스와 행위 분리. ( ex: 리소스: 회원, 행위: 조회, 등록, 삭제 )
• ex: POST /orders/{orderId}/start-delivery (컨트롤 URI) 

 

HTTP 메소드

• GET: 리소스 조회
• POST: 요청 데이터 처리 (주로 등록에 사용)
• PUT: 리소스 덮어쓰기 (있으면 대체, 없으면 생성)
• PATCH: 리소스 부분 변경
• DELETE: 리소스 삭제
• HEAD, OPTIONS, CONNECT, TRACE, ...

 

HTTP 메소드 속성

• 안전; Safe Method
• 멱등; Idempotent Methods
• 캐시 가능; Cachable Methods

 

안전

• 호출해도 리소스 변경 X
• ex: GET, HEAD, OPTIONS, TRACE

 

멱등

• 1번 호출하든 100번 호출하든 결과가 같다
• 자동 복구 매커니즘 등에 사용 (서버가 정상적인 응답을 주지 못했을 때, 클라이언트가 같은 요청을 보내도 되는가?)
• 같은 요청을 여러번 호출 시, 중간에 외부에서 리소스 변경되는 것은 고려하지 않는다.
• ex: GET, PUT, DELETE

 

캐시 가능

• 응답 결과 리소스를 캐시해서 사용해도 되는가?
• ex: GET, HEAD, ...

 

HTTP 메소드 활용

정적 데이터 조회

• 이미지, 정적 텍스트 문서
• 조회는 GET 사용
• 일반적으로 쿼리 사용 없이 사용 가능

 

동적 데이터 조회

• 쿼리 파라미터 사용
• 주로 검색, 게시판 목록에서 정렬 필터에 사용

 

HTML Form 데이터 전송

• 전송 시 method="POST", "GET" 선택 가능
• Content-Type: applicaition/x-www-form-urlencoded 사용
• enctype="multipart/form-data" 멀티로 여러 형식 파일 보낼 수 있다.

 

HTTP API 전송

• 서버 to 서버 전송
• 앱 클라이언트 전송
• 웹 클라이언트 (Ajax 통신)

 

HTTP API 설계 예시

POST 기반

• 회원 목록 /members -> GET
• 회원 등록 /members -> POST
• 회원 조회 /members/{id} -> GET
• 회원 수정 /members/{id} -> PATCH, PUT, POST
• 회원 삭제 /members/{id} -> DELETE

 

POST를 통한 신규 자원 등록 특징

• 서버가 새로 등록된 리소스 URI를 생성해준다.
• 컬렉션: 서버가 관리하는 리소스 디렉토리
• 실무에서 많이 사용

 

PUT 기반

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST

 

PUT을 통한 신규 자원 등록 특징

• 클라이언트는 등록될 리소스의 URI를 알고 있어야 한다.
• 클라이언트가 직접 리소스의 URI를 지정
• 스토어: 클라이언트가 관리하는 리소스 저장소

 

HTML FORM 사용

• 회원 목록     /members -> GET
• 회원 등록 폼 /members/new -> GET
• 회원 등록     /members/new, /members -> POST
• 회원 조회     /members/{id} -> GET
• 회원 수정 폼 /members/{id}/edit -> GET
• 회원 수정     /members/{id}/edit, /members/{id} -> POST
• 회원 삭제     /members/{id}/delete -> POST

 

컨트롤 URI

• HTTP 메소드로 처리하기 애매한 것은 컨트롤 URI 사용
• HTML FORM에서 GET, POST만 지원하는 제약을 해결하기 위해 동사로 된 리소스 경로 사용
• 실무에서도 자주 사용하는 편이지만 사용이 적은 것이 이상적

 

리소스 이름 짓는 방법에 대해서는 restfulapi.net/resource-naming/를 참조하면 좋다.

---

본 글은 김영한님의 유료 강의를 들으며 요약, 정리를 목적으로 작성한 것으로 홍보나 금전적 목적이 없습니다.

제 방식으로 정리한 것으로 강의 내용을 추가/삭제/변경된 부분이 많으며 자세한 설명은 강의 구매를 추천 드립니다.

 

참조

inflean - 김영한님의 '모든 개발자를 위한 HTTP 웹 기본 지식'

inf.run/PHpy

모든 개발자를 위한 HTTP 웹 기본 지식 - 인프런