[Network] - HTTP 메서드 활용과 API 설계

클라이언트가 서버로 데이터 전송하는 방식

쿼리 파라미터를 통한 데이터 전송

💡쿼리 파라미터를 통한 데이터 전송은 URL 끝에? key=value 형태로 데이터를 붙여서 전달하는 방식이다. 

✔️ ex) https://www.example.com/search?q=파스타&sort=latest

🎈주로 GET 요청에서 사용하며 검색어, 정렬 조건, 필터 같은 조회 조건을 전달할 때 사용
      ↳ ex) 구글 검색, 쇼핑몰에서 가격순 정렬을 누를 때 URL에 쿼리 파라미터가 붙는다.

---

메시지 바디를 통한 데이터 전송

💡요청 본문(Body)에 데이터를 담아서 전달하는 방식으로, POST, PUT, PATCH에서 사용.
     ↳ 쿼리 파라미터와 달리 URL에 데이터가 노출되지 않아 더 안전함.

POST /members HTTP/1.1
Content-Type: application/json

✔️ 메시지 바디 ↓
{
"username": "young",
"age": 20
}

🎈회원가입, 상품 주문, 데이터 수정처럼 서버에 데이터를 저장하거나 변경할 때 사용

---

클라이언트가 서버로 데이터 전송하는 4가지 상황

정적 데이터 조회

💡이미지, CSS, JS 파일처럼 항상 같은 내용을 반환하는 파일(정적텍스트 문서)을 조회하는 경우
     ↳ 쿼리 파라미터 미사용

🎈쿼리 파라미터 없이 경로만으로 단순하게 조회한다. 파일 경로만 알면 되기 때문에 추가적인 데이터가 필요 없다. 또한 GET 요청이기 때문에 브라우저가 캐싱해 두면 다음에는 서버 요청 없이 바로 사용할 수 있다.

---

동적 데이터 조회

💡검색어나 정렬 조건에 따라 결과가 달라지는 경우
     ↳ 쿼리 파라미터를 기반으로 결과를 동적으로 생성

✔️ 예시
GET /search?q=파스타&sort=latest HTTP/1.1
Host: www.example.com

✔️ 쿼리 파라미터 사용 ↓
정렬 조건 : ?sort=latest (최신순)
검색어 : ?q=파스타

🎈주로 검색, 게시판 목록에서 정렬 필터(검색어), 조회 조건을 줄여주는 필터, 조회 결과를 정렬하는 정렬 조건에 사용
    ↳ 조회는 GET을 사용하며, GET은 쿼리 파라미터를 사용해서 데이터를 전달한다.

---

HTML Form을 통한 데이터 전송

💡웹 페이지의 <form> 태그를 통해 데이터를 전송하는 방식
      ↳ 주로 회원가입, 로그인, 상품 주문 같은 상황에서 사용 (웹 페이지에서 사용자가 데이터 입력 -> 서버 전송)

✔️ 클라이언트 요청(브라우저에서 작성하는 Form)
<form action="/members" method="post">
     <input type="text" name="username" />
     <input type="text" name="age" />
     <button type="submit">전송</button>
</form>

✔️ Form 전송하면 브라우저가 자동으로 생성하는 HTTP 요청
POST /members HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

username=young&age=20

✔️ 클라이언트 :
- username에 "young", age에 "20" 입력 후 전송 

✔️ 브라우저 
1. POST 방식으로 /members에 보내야 하는 걸 인지
2. 데이터를 username=young&age20 형태로 변환
3. HTTP 요청 패킷 생성
4. 서버로 전송

multipart/form-data

💡여러 종류의 데이터를 파트로 나눠서 한 번에 전송( 일반 Form전송은 텍스트 데이터만 전송 가능) 
    ↳ 프로필 사진처럼 파일을 업로드할 때는 텍스트와 바이너리 데이터 함께 전송해야 하는데, 이때 사용

바이너리 데이터란 텍스트 형식이 아닌 이미지, 오디오, 실행 파일 등을 의미

✔️ 사용 방법
<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="text" name="username" value="young"/>
  <input type="file" name="file"/>
  <button type="submit">전송</button>
</form>

각 파트마다 Content-Type이 다르게 설정되어 텍스트는 텍스트로, 이미지는 이미지로 각각의 타입에 맞게 전송

🎈 Form은 GET과 POST 두 가지 메서드만 지원한다.
      ↳ GET으로 전송하면 쿼리 파라미터로, POST로 전송하면 메시지 바디로 데이터가 전달된다.
🎈PUT, PATCH, DELETE는 Form에서 직접 지원하지 않기 때문에 이런 경우에는 HTP API 방식을 사용해야 한다.

---

HTTP API 데이터 전송

💡HTTP Form을 사용하지 않고, 코드로 직접 HTTP 요청을 만들어서 전송하는 방식

사용 상황

상황	설명	예시
서버 to 서버	- 백엔드 시스템끼리 통신할 때 사용 - HTML 전혀 없이 기계끼리 데이터를 주고 받는 상황 - 사람의 개입없이 서버끼리 자동으로 API 호출	주문 서버 -> 결제 서버 배송 서버 -> 알림 서버
앱 클라이언트	- 아이폰, 안드로이드 앱에서 서버와 통신할 때 사용 - 앱은 HTML Form이 없어서, HTTP API로 직접 요청	앱에서 로그인 버튼 클릭 POST /login { "id": "young", "pw": "1234" } 서버 응
웹 클라이언트 (AJAX)	- HTML Form대신 JavaScript로 HTTP 요청 직접 보냄 - React, Vue 등 프론트엔드 프레임워크에서 주로 사용	React, Vue + JSON *과거에는 XML을 많이 사용 했지만 JSON이 훨씬 가볍고 읽기 쉬워 대부분 JSON 사용

JSON 방식

// JSON - 읽기 쉽고 가볍다
{ "username": "young", "age": 20 }

// XML - 태그가 많아서 무겁다
<member>
  <username>young</username>
  <age>20</age>
</member>

---

HTTP API 설계 예시

💡URI는 리소스만 식별해야 하고, 행위는 HTTP 메서드로 표현

❗잘못된 설계
GET /members/1/get → 1번 회원 조회
GET /members/1/delete → 1번 회원 삭제
GET /members/1/update → 1번 회원 수정

✔️ 올바른 설계
GET /members/1 → 1번 회원 조회
DELETE /members/1 → 1번 회원 삭제
PATCH /members/1 → 1번 회원 수정

API 설계 - 컬렉션(Collection, POST 기반)

💡 컬렉션은 서버가 관리하는 리소스 디렉터리로 핵심은 서버가 리소스의 URI를 직접 생성하고 관리한다는 점
       ↳ 클라이언트는 /members 까지만 알면 되고, 새로 생성될 /members/100의 100이라는 ID는 서버가 자동 생성

✔️ 회원 관리 API 설계(컬렉션 - /members)
회원 목록 조회  GET   /members
회원 등록          POST /members
회원 조회          GET /members/{id}
회원 수정          PATCH /members/{id}
회원 삭제          DELETE /members/{id}

✔️ URI는 /members 하나로 통일하고, 메서드만 바꿔 행위를 구분
      ↳ 같은 URI(/members/1)이라도 메서드에 따라 전혀 다르게 동작

POST 기반의 신규 자원 등록

💡POST로 등록할 때 가장 중요한 특징은 클라이언트가 등록될 리소스의 URI를 모른다는 점
     ↳ 클라이언트는 /members로 요청만 하면 되고, 새로 만들어진 리소스의 URI는 서버가 Location 헤더로 돌려줌

---

API 설계 - 스토어(Store, PUT 기반)

💡컬렉션은 서버가 URI를 생성하고 관리했지만, 스토어는 클라이언트가 리소스의 URI를 알고 직접 관리하는 저장소
     ↳ 주로 정적 콘텐츠 관리, 원격 파일 관리 같은 상황에서 사용

 

✔️ 파일 관리 API 설계

파일 목록 조회 GET /files
파일 조회         GET /files/{filename}
파일 등록         PUT /files/{filename}   -> 컬렉션과 달리 파일 등록에 PUT 사용
파일 삭제         DELETE /files/{filename}
파일 대량 등록 POST /files

PUT 기반의 신규 자원 등록 

💡PUT으로 등록할 때 가장 중요한 특징은 클라이언트가 리소스의 URI를 직접 알고 지정한다는 점

① 클라이언트 요청
PUT /files/star.jpg
→ "star.jpg라는 이름으로 파일 저장해 줘"
→ 클라이언트가 URI를 직접 지정!

② 서버
→ /files/star.jpg 에 파일 저장
→ 이미 있으면 덮어씀, 없으면 새로 생성(완전히 대체)

---

컬렉션 vs 스토어

구분	컬렉션	스토어
기반 메서드	POST	PUT
URI 생성	서버가 자동 생성	클라이언트가 직접 지정
예시	회원 관리	파일 관리

🎈실무에서는 대부분 컬렉션 사용, 스토어 방식은 파일 업로드처럼 클라이언트가 파일명을 직접 정해야 하는 경우 사용 

---

HTML Form

💡HTML Form은 GET과 POST만 지원해서 앞의 API 설계 방식 그대로 적용 어려움(PATCH, PUT, DELETE 사용 불가)
     ↳ AJAX 사용하면 제약 해결 가능

✔️ 웹 페이지 회원 관리 설계

회원 목록          GET /members
회원 등록 폼      GET /members/new
회원 등록          POST /members/new 또는 /members
회원 조회          GET /members/{id}
회원 수정 폼      GET /members/{id}/edit
회원 수정          POST /members/{id}/edit 또는 /members/{id}
회원 삭제          POST /members/{id}/delete

API 설계와의 차이

❗DELETE, PATCH를 쓸 수 없으니 URI에 /delete, /edit 같은 동사를 붙여서 행위를 표현해야 함

✔️ API 설계 (제약 없음)
DELETE /members/{id} → 삭제
PATCH /members/{id} → 수정

✔️ HTML Form (GET, POST만 가능)
POST /members/{id}/delete → 삭제
POST /members/{id}/edit → 수정

 컨트롤 URI

💡컨트롤 URI란 HTTP 메서드 만으로 해결이 어려울 때 URI에 동사를 넣는 것입니다.
     ↳ 실무에서 많이 사용하며, 최대한 리소스 중심으로 설계하고 도저히 안 될 때 대안으로 사용 

---

URI 설계 개념 정리

명칭	의미	설명	예시
문서(Document)	단일 개념을 나타내는 URI	파일 하나, 데이터베이스 row 하나처럼 단 하나의 리소스만 가리킴	/members/100 /files/star.jpg
컬렉션(Collection)	서버가 관리하는 리소스 디렉토리	서버가 POST 기반으로 URI를 생성 및 관리	/members POST로 등록 서버 :  /mebmers/100 생
스토어(Store)	클라이언트가 관리하는 자원 저장소	클라이언트가 PUT 기반으로 URI를 알고 직접 지정	/files PUT /files/star.jpg
컨트롤러(Controller)	문서, 컬렉션, 스토어만으로 해결하기 어려운 경우 사용	URI에 동사를 직접 사용	/members/{id}/delete /members/{id}/edit