HTTP Method

HTTP API

좋은 URI 설계란?

=> 리소스 식별에 중점을 두자. 리소스를 URI에 매핑해야한다.

 

- 리소스란...?

회원목록, 회원등록, 회원삭제 등의 기능이 있을 때 각각의 '행위'가 아닌 행위의 '주체'를 말한다.

즉, '회원' 이라는 명사를 말한다.

 

- 그럼 행위는 어떻게 구분...?

HTTP 메소드(행위)로 구분한다

---

HTTP Method

GET : 리소스 조회

서버에 전달하고 싶은 데이터는 query param을 통해서 전달

 

POST : 요청 데이터 처리, 주로 등록에 사용

메세지 바디를 통해 서버로 요청 데이터 전달하여 처리를 요청

=> 메세지 바디를 통해 들어온 데이터를 처리하는 모든 기능을 수행

1. 새 리소스 생성(등록) : 서버가 아직 식별하지 않은 새 리소스 생성

2. 요청 데이터 처리 : 단순히 데이터를 생성하거나, 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우(서버에서 어떠한 변화가 있을 경우)

3. 다른 메서드로 처리하기 애매한 경우

 

PUT : 리소스를 대체, 해당 리소스가 없으면 생성

리소스가 있으면 대체(덮어쓰기), 없으면 생성

* 클라이언트가 리소스 위치를 알고 URI를 직접 지정

기존 리소스를 완전히 대체하기 때문에 기존에 2개의 데이터가 있는 서버에 1개의 데이터를 put 시키면 서버에는 1개의 데이터만 존재하게 된다.

 

PATCH : 리소스 부분 변경

put이 기존 리소스를 완전 대체하는 것과 달리 부분 리소스 변경이 가능하다.

( patch가 지원되지 않을 경우 post )

 

DELETE : 리소스 삭제

---

HTTP 메소드의 속성

안전 : 호출 시 리소스를 변경 여부

 

멱등 : 한번호출한 결과와 100번 호출한 결과가 같은 지 여부

- 자동복구 메커니즘에 활용 가능

( 서버에서 처리결과에 대한 응답이 없을 경우 같은 기능을 재요청해도 결과에 문제가 없는경우 판단근거 )

=> 다른 클라이언트( 외부 )의 요인으로 변경된 리소스가 변경되는 것은 고려하지 않는다. 클라이언트 본인의 요청이 기준

 

캐시가능 : 응답 결과 리소스를 캐시해서 사용해도 되는지 여부

GET, HEAD, POST, PATCH 캐시가능하지만 실제로는 GET, HEAD 정도만 가능

( POST, PATCH는 body 본문 내용까지 캐시 키로 고려해야하지만 구현하기 어렵다. )

---

HTTP 메소드 활용

 

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

1. 쿼리 파라미터

- GET

- 주로 정렬 필터 ( 검색어 )

2. 메세지 바디

- POST, PUT, PATCH

- 회원가입, 상품 주문, 리소스 등록/변경

 

정적 데이터 조회 ( 이미지, 정적 텍스트 문서 )

정적 데이터는 일반적으로 쿼리 파라미터 없이 리소스 경로로 단순 조회 가능

 

동적 데이터 조회 ( 검색, 게시판 목록 정렬 필터, 검색어 )

조회 조건을 줄여주는 필터, 조회 결과를 정렬하는 정렬 조건에 주로 사용

 

HTML Form을 통한 데이터 전송 ( 회원 가입, 상품 주문, 데이터 변경 )

조회성 form 일 경우 GET을 써도 되지만, 리소스에 변형이 가해지는 form일 경우 POST를 사용해야한다.

( GET, POST만 지원함 )

Content-Type	설명
application/x-www-form-urlencoded	form의 내용을 메세지 바디를 통해 전송 (key=value, 쿼리 파라미터 형식) 전송 데이터를 url encoding 처리
multipart/form-data	파일 업로드 같은 바이너리 데이터 전송 시 사용 다른 종류의 파일과 form의 내용을 함께 전송 가능

 

HTTP API를 통한 데이터 전송 ( 회원 가입, 상품 주문, 데이터 변경, 서버 to 서버, 앱 클라이언트, 웹 클라이언트(Ajax) )

서버 to 서버 : 백엔드 시스템 통신

앱 클라이언트

웹 클라이언트 : 자바스크립트를 통한 통신에 사용( Ajax )

Content-Type:application/json 을 주로 사용

---

HTTP API 설계 예시

 

HTTP API - 컬렉션

POST 기반 등록 ( 회원 관리 API 제공 )

- 회원 목록 /members => GET ( 쿼리 파라미터를 통해 검색, 정렬조건을 서버에 전달 )

- 회원 등록 /members => POST

- 회원 조회 /members/{id} => GET

- 회원 수정 /members/{id} => PATCH(부분수정), PUT(전체수정), POST

- 회원 삭제 /members/{id} => DELETE

 

* 클라이언트는 등록될 리소스의 URI를 모른다.

* 서버가 새로 등록된 리소스 URI를 생성해준다.

* 컬렉션 : 서버가 관리하는 리소스 디렉토리

( /members )

 

HTTP API - 스토어

PUT 기반 등록 ( 정적 컨텐츠 관리, 원격 파일 관리 )

- 파일 목록 /files => GET

- 파일 조회 /files/{filename} => GET

- 파일 등록 /files/{filename} => PUT ( 기존 파일이 있으면 덮어쓰기, 없으면 새로 등록 )

- 파일 삭제 /files/{filename} => DELETE

- 파일 대량 등록 /files => POST

 

* 클라이언트가 리소스 URI를 알고 있어야한다.

* 클라이언트가 직접 리소스를 관리

* 스토어 : 클라이언트가 관리하는 리소스 저장소

( /files )

 

HTML FORM 사용

GET, POST만 지원 ( 웹 페이지 회원관리 )

- 회원 목록      /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 : GET, POST만 지원하므로 URI에 동사(행위)로 된 리소스 경로 사용 ( 최소화 해야함 )

( new, edit, delete 등 )

---

좋은 URI 설계 개념

https://restfulapi.net/resource-naming 

REST API - URL Naming Conventions

문서( document ) : 단일 개념 ( 파일 하나, 객체 인스턴스, 데이터베이스 row )

컬렉션 ( collection ) : 서버가 관리하는 리소스 디렉토리, 서버가 리소스의 URI를 생성하고 관리

스토어 ( store ) : 클라이언트가 관리하는 자원 저장소, 클라이언트가 리소스의 URI를 알고 관리

컨트롤러 ( controller ), 컨트롤 URI : 문서, 컬렉션, 스토어를 해결하기 어려운 추가 프로세스 실행, 동사를 직접 사용