HTTP & RESTful API

1. HTTP란?

HTTP(하이퍼텍스트 전송 프로토콜, HyperText Transfer Protocol)는 월드 와이드 웹에서 클라이언트와 서버 간에 데이터를 주고받기 위한 통신 규약입니다. 이 프로토콜은 텍스트, 이미지, 비디오, JSON 등 다양한 형식의 데이터를 전송할 수 있으며, RESTful API의 기반이 됩니다.

2. RESTful API 개요

REST(Representational State Transfer)는 분산 시스템을 위한 소프트웨어 아키텍처 스타일로, 리소스 기반의 상호작용을 강조합니다. RESTful API는 이러한 REST 원칙을 따르는 웹 API를 의미하며, 클라이언트와 서버 간의 통신에 HTTP 메서드를 활용합니다.

3. HTTP 메서드의 종류와 상세 특징

3.1 GET (Fetch - 가져오기)

목적: 서버에서 리소스를 조회하거나 가져오는 데 사용됩니다.

특징:

• 캐싱: GET 요청은 브라우저나 중간 프록시 서버에서 캐시될 수 있습니다. 이는 동일한 요청에 대한 응답 시간을 단축하고 네트워크 부하를 줄입니다.
• 안전성(Safe): 서버의 상태를 변경하지 않으므로 안전한 메서드로 분류됩니다.
• 멱등성(Idempotent): 동일한 요청을 여러 번 보내도 서버의 상태가 변하지 않습니다.
• 데이터 전송 위치: 주로 URL의 쿼리 파라미터(Query Parameters)를 통해 데이터를 전송합니다.

사용 예시:

 

GET /api/products?category=electronics&page=2

이 요청은 electronics 카테고리의 제품을 페이지 2에서 조회하는 것입니다.

쿼리 파라미터 예시:

• category=electronics: 제품의 카테고리를 지정
• page=2: 페이지 번호 지정

3.2 POST (생성하기)

목적: 서버에 새로운 리소스를 생성하거나 특정 작업을 수행합니다.

특징:

• 캐싱 불가: 일반적으로 캐시되지 않습니다.
• 안전성 없음: 서버의 상태를 변경하므로 안전하지 않은 메서드입니다.
• 멱등성 없음: 동일한 요청을 여러 번 보내면 여러 개의 리소스가 생성될 수 있습니다.
• 데이터 전송 위치: 요청의 본문(Body)을 통해 데이터를 전송합니다.

사용 예시:

POST /api/products
Content-Type: application/json

{
  "name": "새 제품",
  "price": 10000,
  "category": "electronics"
}

이 요청은 새로운 제품을 생성하는 것입니다.

3.3 PUT (전체 수정하기)

목적: 기존 리소스를 완전히 대체하거나 생성합니다.

특징:

• 멱등성: 동일한 요청을 여러 번 보내도 결과가 동일합니다.
• 캐싱 불가: 일반적으로 캐시되지 않습니다.
• 데이터 전송 위치: 요청의 본문(Body)을 통해 전체 리소스 데이터를 전송합니다.

사용 예시:

PUT /api/products/1
Content-Type: application/json

{
  "name": "업데이트된 제품",
  "price": 12000,
  "category": "electronics"
}

이 요청은 ID가 1인 제품의 전체 정보를 업데이트하거나, 해당 ID의 리소스가 없을 경우 생성합니다.

3.4 PATCH (부분 수정하기)

목적: 기존 리소스의 일부를 수정합니다.

특징:

• 멱등성(조건부): 구현에 따라 다르지만, 일반적으로 동일한 요청을 여러 번 보내도 결과가 동일합니다.
• 캐싱 불가: 일반적으로 캐시되지 않습니다.
• 데이터 전송 위치: 요청의 본문(Body)을 통해 수정할 부분의 데이터를 전송합니다.

사용 예시:

PATCH /api/products/1
Content-Type: application/json

{
  "price": 11000
}

이 요청은 ID가 1인 제품의 가격만을 수정합니다.

3.5 DELETE (삭제하기)

목적: 서버에서 특정 리소스를 삭제합니다.

특징:

• 멱등성: 동일한 요청을 여러 번 보내도 결과가 동일합니다. 이미 삭제된 리소스에 대한 삭제 요청은 추가적인 변화를 일으키지 않습니다.
• 캐싱 불가: 일반적으로 캐시되지 않습니다.
• 데이터 전송 위치: 보통 본문(Body)을 사용하지 않으며, URL을 통해 삭제할 리소스를 지정합니다.

사용 예시:

DELETE /api/products/1

이 요청은 ID가 1인 제품을 삭제합니다.

4. 요청 데이터의 전송 방식

4.1 쿼리 파라미터(Query Parameters)

• 사용 위치: URL의 '?' 다음에 키-값 쌍으로 추가됩니다.
• 용도: 필터링, 정렬, 페이징 등 리소스의 조회 조건을 지정할 때 주로 사용됩니다.
• 예시:

GET /api/products?category=electronics&sort=price_desc&page=2

4.2 경로 파라미터(Path Parameters)

• 사용 위치: URL의 경로 부분에 변수로 사용됩니다.
• 용도: 특정 리소스를 식별할 때 사용됩니다.
• 예시:
  여기서 1은 제품의 ID를 나타내는 경로 파라미터입니다.

GET /api/products/1

4.3 본문(Body)

• 사용 위치: HTTP 요청의 본문에 JSON, XML 등으로 데이터를 포함합니다.
• 용도: 리소스를 생성하거나 업데이트할 때 주로 사용됩니다.
• 예시:

POST /api/products
Content-Type: application/json

{
  "name": "새 제품",
  "price": 10000,
  "category": "electronics"
}

5. 기타 고려 사항

5.1 헤더(Headers)

HTTP 헤더는 요청이나 응답에 대한 부가 정보를 전달하는 데 사용됩니다. 중요한 헤더 중 일부는 다음과 같습니다:

• Content-Type: 본문의 데이터 타입을 지정합니다. 예: application/json
• Authorization: 인증 정보를 전달합니다. 예: Bearer {token}
• Accept: 클라이언트가 수용 가능한 응답 데이터 타입을 지정합니다. 예: application/json

5.2 상태 코드(Status Codes)

서버는 클라이언트의 요청에 대한 결과를 상태 코드로 응답합니다. 주요 상태 코드는 다음과 같습니다:

• 200 OK: 요청이 성공적으로 처리되었습니다.
• 201 Created: 새로운 리소스가 성공적으로 생성되었습니다.
• 400 Bad Request: 잘못된 요청입니다. 요청 문법이 잘못되었거나 필요한 파라미터가 누락되었습니다.
• 401 Unauthorized: 인증이 필요합니다.
• 403 Forbidden: 요청이 허용되지 않습니다.
• 404 Not Found: 요청한 리소스를 찾을 수 없습니다.
• 500 Internal Server Error: 서버에서 오류가 발생했습니다.

5.3 안전성(Safety)과 멱등성(Idempotency)

• 안전성(Safety): 메서드가 서버의 상태를 변경하지 않으면 안전하다고 합니다. 예: GET
• 멱등성(Idempotency): 동일한 요청을 여러 번 보내도 결과가 동일하면 멱등하다고 합니다. 예: PUT, DELETE

6. RESTful API 메서드 비교 표

HTTP 메서드	목적	데이터 전송 위치	캐싱	안전성	멱등성	사용 예시
GET	리소스 조회	URL(쿼리 파라미터)	가능	안전	있음	GET /api/products/1
POST	새로운 리소스 생성	본문(Body)	불가능	불안전	없음	POST /api/products
PUT	기존 리소스 대체	본문(Body)	불가능	불안전	있음	PUT /api/products/1
PATCH	기존 리소스 부분 수정	본문(Body)	불가능	불안전	조건부	PATCH /api/products/1
DELETE	리소스 삭제	URL(경로 파라미터)	불가능	불안전	있음	DELETE /api/products/1

7. 결론

RESTful API는 HTTP 메서드의 특성과 원칙을 이해하고 적절하게 활용하는 것이 중요합니다. 각 메서드는 고유한 목적과 특징을 가지며, 데이터 전송 방식, 캐싱 여부, 안전성, 멱등성 등 다양한 요소를 고려해야 합니다. 올바른 설계와 구현을 통해 효율적이고 신뢰성 있는 API를 구축할 수 있습니다.