jhpka's blog
로그인회원가입

[Web] REST API 요청 필수 요소 정리

Backend
Admin User
Network

모든 API 요청의 최소 구성 요소

  • HTTP 메서드
  • URL
text
GET https://api.example.com/users

상황별 필수 요소

1. GET 요청 (조회)

기본

text
GET https://api.example.com/users

인증 필요

text
GET https://api.example.com/users
Authorization: Bearer token123

쿼리 파라미터 포함

text
GET https://api.example.com/users?page=1&limit=10
Authorization: Bearer token123

2. POST 요청 (생성)

JSON 본문

text
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "홍길동",
  "email": "hong@example.com"
}

인증 + JSON 본문

text
POST https://api.example.com/users
Authorization: Bearer token123
Content-Type: application/json

{
  "name": "홍길동"
}

본문 없는 POST

text
POST https://api.example.com/users/123/activate
Authorization: Bearer token123

3. PUT/PATCH 요청 (수정)

PUT (전체 수정)

text
PUT https://api.example.com/users/123
Authorization: Bearer token123
Content-Type: application/json

{
  "name": "김철수",
  "email": "kim@example.com",
  "age": 30
}

PATCH (부분 수정)

text
PATCH https://api.example.com/users/123
Authorization: Bearer token123
Content-Type: application/json

{
  "name": "김철수"
}

4. DELETE 요청 (삭제)

기본

text
DELETE https://api.example.com/users/123
Authorization: Bearer token123

본문 포함 (드물게 사용)

text
DELETE https://api.example.com/users
Authorization: Bearer token123
Content-Type: application/json

{
  "ids": [1, 2, 3]
}

5. 파일 업로드

text
POST https://api.example.com/upload
Authorization: Bearer token123
Content-Type: multipart/form-data

------WebKitFormBoundary...
Content-Disposition: form-data; name="file"; filename="image.jpg"
Content-Type: image/jpeg

(바이너리 데이터)
------WebKitFormBoundary...

6. 폼 데이터

text
POST https://api.example.com/login
Content-Type: application/x-www-form-urlencoded

username=hong&password=1234

필수 요소 판단 기준

Content-Type 필요 여부

text
요청 본문(body)이 있는가?
├─ YES → Content-Type 필수
│   ├─ JSON → Content-Type: application/json
│   ├─ 폼 → Content-Type: application/x-www-form-urlencoded
│   └─ 파일 → Content-Type: multipart/form-data
└─ NO → Content-Type 불필요

Authorization 필요 여부

text
인증이 필요한가?
├─ YES → Authorization 필수
│   ├─ Bearer 토큰 → Authorization: Bearer token123
│   ├─ Basic 인증 → Authorization: Basic base64string
│   └─ API 키 → Authorization: ApiKey your-key
└─ NO → Authorization 불필요

실전 예시

예시 1: 공개 API 조회

text
GET https://api.example.com/posts
  • ✅ 최소 구성 (인증, 본문 불필요)

예시 2: 로그인

text
POST https://api.example.com/auth/login
Content-Type: application/json

{
  "username": "hong",
  "password": "1234"
}
  • ✅ Content-Type 필수 (본문 존재)
  • ❌ Authorization 불필요 (로그인 전)

예시 3: 인증된 데이터 조회

text
GET https://api.example.com/me
Authorization: Bearer eyJhbGc...
  • ✅ Authorization 필수
  • ❌ Content-Type 불필요 (본문 없음)

예시 4: 사용자 정보 수정

text
PATCH https://api.example.com/users/123
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "email": "newemail@example.com"
}
  • ✅ Authorization 필수 (인증 필요)
  • ✅ Content-Type 필수 (본문 존재)

예시 5: 파일 업로드

text
POST https://api.example.com/upload
Authorization: Bearer eyJhbGc...
Content-Type: multipart/form-data

(파일 데이터)
  • ✅ Authorization 필수
  • ✅ Content-Type: multipart/form-data 필수

예시 6: 검색 (쿼리 파라미터)

text
GET https://api.example.com/search?q=javascript&page=1
  • ✅ 쿼리 파라미터는 URL에 포함
  • ❌ 헤더 불필요 (공개 검색)

예시 7: 로그아웃

text
POST https://api.example.com/auth/logout
Authorization: Bearer eyJhbGc...
  • ✅ Authorization 필수 (대상 식별)
  • ❌ Content-Type 불필요 (본문 없음)

선택적 헤더

자주 사용하는 선택적 헤더

text
# 응답 형식 지정
Accept: application/json

# 언어 지정
Accept-Language: ko-KR,ko;q=0.9

# 캐시 제어
Cache-Control: no-cache

# CORS
Origin: https://example.com

# 커스텀 헤더
X-API-Version: 2.0
X-Request-ID: abc123

사용 시점

기본 요청

text
GET https://api.example.com/users
Authorization: Bearer token123

JSON 응답 명시

text
GET https://api.example.com/users
Authorization: Bearer token123
Accept: application/json

한국어 응답 요청

text
GET https://api.example.com/users
Authorization: Bearer token123
Accept-Language: ko-KR

API 버전 지정

text
GET https://api.example.com/users
Authorization: Bearer token123
X-API-Version: 2.0

헤더 포함 기준

✅ 반드시 포함

  • HTTP 메서드
  • 전체 URL
  • 본문 있으면 Content-Type
  • 인증 필요하면 Authorization

⚠️ 상황에 따라 포함

  • Accept (응답 형식 지정)
  • Accept-Language (언어 지정)
  • 커스텀 헤더 (API 특정 요구사항)

❌ 보통 생략

  • User-Agent (브라우저 자동)
  • Host (URL에 포함)
  • Content-Length (자동 계산)
  • Connection (브라우저 자동)

API 문서화 예시

text
## 사용자 생성

필수 헤더:
- Content-Type: application/json
- Authorization: Bearer {token}

요청:
POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "string",
  "email": "string"
}

최소 표기

text
POST https://api.example.com/users
Authorization: Bearer token123
Content-Type: application/json

{"name": "홍길동", "email": "hong@example.com"}

핵심 규칙

  1. 본문(body) 있으면 → Content-Type 필수
  2. 인증 필요하면 → Authorization 필수
  3. 나머지는 상황에 따라 선택
댓글을 불러오는 중...