API 서비스 Nginx 설정¶

API 서비스(REST API, 내부 API, BFF, 인증/결제 API 등)를 제공하기 위한 Nginx 설정 기준 정의함. API 서비스 특성에 따라 필요한 항목만 추가 또는 override함.

1. 적용 대상¶

REST / JSON 기반 API
사내 API
외부 공개 API
Web / Mobile / Backend 간 통신용 API

2. API 서비스 특성¶

API 서비스는 다음과 같은 특성을 가짐.

요청 빈도 높음
요청/응답 크기 작음
실패 시 재시도 발생 가능함
사용자 체감보다 시스템 안정성이 중요함
짧은 timeout과 명확한 오류 응답 필요함

3. 서비스별 필수 설정¶

3.1 요청 크기 제한¶

API 요청은 일반적으로 큰 body를 필요로 하지 않음.

client_max_body_size 5m;

JSON / Form 기반 API에 충분함
파일 업로드 API는 별도 location에서 상향 권장함

3.2 Timeout 정책¶

API는 장시간 연결을 유지하지 않는 것이 원칙임.

proxy_connect_timeout 10s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;

Backend 장애 시 빠른 실패 유도
무한 대기 방지 목적
장애 전파 최소화 목적

3.3 프록시 헤더 전달¶

Backend에서 요청 정보를 정확히 인식하도록 표준 헤더 전달 필요함.

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

3.4 Buffering 정책¶

API 서비스는 실시간성이 중요하고 응답 크기가 작음.
Nginx buffering 이점이 거의 없으므로 명시적으로 비활성화함.

proxy_request_buffering off;
proxy_buffering off;

의도

요청/응답 지연 최소화
대량 요청 시 디스크 I/O 방지
API 응답 특성 예측 가능성 확보

3.5 오류 응답 처리 기준¶

API 서비스는 HTML error_page 사용을 지양함
Backend에서 JSON 기반 오류 응답 반환을 기본 원칙으로 함
Nginx error_page 설정은 서비스 정책에 따라 별도 정의함

의도

클라이언트(Web/App)에서 오류 처리 일관성 확보
장애 시 원인 파악 용이성 확보

3.6 HTTP Method 노출 원칙 (보안)¶

API는 필요한 HTTP Method만 노출하는 것이 바람직함
불필요한 Method는 Nginx 레벨에서 차단 가능함
실제 적용 여부는 서비스 보안 정책에 따름

4. 권장 server 설정 예시¶

server {
    listen 443 ssl;
    server_name api.example.com;

    client_max_body_size 5m;

    location / {
        proxy_pass http://API_BACKEND_UPSTREAM;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 10s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;

        proxy_request_buffering off;
        proxy_buffering off;
    }
}

5. 운영 점검 항목¶

413 오류 발생 시 client_max_body_size 점검 필요함
504 오류 빈번 시 backend 성능 또는 timeout 재검토 필요함
재시도 트래픽 증가 여부 모니터링 필요함
장애 시 응답 지연보다 빠른 실패가 발생하는지 확인 필요함

6. API 트래픽 특성 및 rate / connection limit 적용 기준¶

6.1 API 트래픽 특성¶

요청 수 많음
연결 유지 시간 짧음
동일 클라이언트의 반복 호출 빈번함
악의적 트래픽 발생 가능성 높음

6.2 rate / connection limit 적용 원칙¶

API 서비스는 rate limit 적용 효과가 큼
connection limit보다 rate limit 중심으로 제어함
과도한 제한은 정상 사용자 장애로 이어질 수 있음

6.3 일반적인 권장 수치 예시 (참고)¶

limit_conn conn_limit 20;
limit_req zone=req_limit burst=20 nodelay;

전제: req_limit, conn_limit zone은 04-Nginx Global 설정 (공통 기반)에서 먼저 정의되어 있어야 함.

외부 공개 API 기준 예시임
내부 API는 더 완화 가능함

6.4 상황별 적용 예시¶

1) 내부 전용 API¶

목적: 안정성 확보
권장 방향:
- limit_conn: 20 ~ 50 수준
- limit_req: 적용하지 않거나 매우 완화

2) 외부 공개 API¶

목적: 남용 및 공격 방어
권장 방향:
- limit_conn: 10 ~ 20 수준
- limit_req: 적극 적용
- 인증 기반 rate limit 병행 권장

3) 인증 / 결제 API¶

목적: 보안 및 안정성 최우선
권장 방향:
- limit_conn: 낮게 설정
- limit_req: 엄격 적용
- 실패 응답 시 명확한 에러 코드 반환

7. 정리¶

API 서비스는 짧은 timeout + 명확한 실패 처리가 핵심임
rate limit은 필수 보안 요소임
connection limit은 보조 수단으로 사용함