Skip to main content

​
HTTP & API 기초

RAG, Agent, LLMOps 파이프라인은 대부분 API 호출로 연결됩니다. API 기본기를 모르면 기능은 동작해도 운영에서 쉽게 무너집니다.

​
학습 목표

  • HTTP 메서드와 상태코드를 정확히 구분할 수 있습니다.
  • 멱등성, 타임아웃, 재시도 정책을 설계할 수 있습니다.
  • REST와 GraphQL의 차이를 이해하고 상황에 맞게 선택할 수 있습니다.
  • API 변경 시 호환성과 버전 전략을 설명할 수 있습니다.

​
HTTP 메서드 비교

메서드용도멱등성요청 본문대표 사례
GET리소스 조회O없음모델 상태 조회
POST리소스 생성X있음추론 작업 생성
PUT전체 교체O있음설정 전체 업데이트
PATCH부분 수정X있음파라미터 일부 변경
DELETE리소스 삭제O없음/선택실험 데이터 삭제
멱등성(Idempotency)이란 같은 요청을 여러 번 보내도 결과가 동일하게 유지되는 성질입니다. POST는 멱등하지 않으므로 재시도 시 중복 생성을 방지하는 별도 설계가 필요합니다.

​
HTTP 상태 코드 주요 분류

코드의미대응 주체예시
200성공-정상 응답
201생성 완료-리소스 생성 성공
400잘못된 요청클라이언트파라미터 누락/형식 오류
401인증 실패클라이언트토큰 만료, 키 누락
403권한 없음클라이언트접근 권한 부족
404리소스 없음클라이언트잘못된 엔드포인트
429요청 과다클라이언트Rate Limit 초과
500서버 내부 오류서버 운영자서버 코드 버그
502게이트웨이 오류서버 운영자업스트림 서버 장애
503서비스 불가서버 운영자서버 과부하/유지보수
504게이트웨이 타임아웃서버 운영자업스트림 응답 지연
LLM API 호출 시 429(Rate Limit)와 503(과부하)을 구분해야 합니다. 429는 잠시 대기 후 재시도, 503은 fallback 모델로 전환하는 전략이 일반적입니다.

​
실무 설계 원칙

  1. URL은 리소스 중심으로 설계합니다. (/v1/models/{id}/predict)
  2. 요청/응답 스키마를 문서화합니다. (OpenAPI/Swagger 권장)
  3. 에러 포맷을 서비스 전체에서 통일합니다.
  4. 타임아웃/재시도/지수 백오프 정책을 기본값으로 제공합니다.
  5. 버전(/v1, /v2) 정책으로 하위 호환성을 관리합니다.

​
REST vs GraphQL 비교

항목RESTGraphQL
엔드포인트리소스별 다수단일 엔드포인트
데이터 선택서버가 결정클라이언트가 필드 지정
Over-fetching발생 가능필요한 필드만 요청
캐싱HTTP 캐싱 활용 용이별도 캐싱 전략 필요
학습 곡선낮음중간
적합 사례CRUD 중심 API복잡한 관계형 데이터 조회
AI/ML 파이프라인에서는 REST가 압도적으로 많이 사용됩니다. 모델 서빙(vLLM, TGI), 벡터DB, LLM 게이트웨이 모두 REST 기반입니다. GraphQL은 프론트엔드 BFF(Backend For Frontend) 구성에서 주로 활용됩니다.

​
요청/응답 예시

POST /v1/jobs HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{"task":"embedding","dataset_id":"ds_001"}

{
  "job_id": "job_123",
  "status": "queued"
}

​
curl로 API 테스트하기

# GET 요청 - 모델 상태 조회
curl -s https://api.example.com/v1/models/gpt-4 \
  -H "Authorization: Bearer $API_KEY" | jq .

# POST 요청 - 추론 작업 생성
curl -X POST https://api.example.com/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"model":"gpt-4","prompt":"Hello","max_tokens":100}'

# 응답 헤더만 확인 (상태 코드 + Rate Limit 정보)
curl -I https://api.example.com/v1/models
jq를 함께 사용하면 JSON 응답을 보기 좋게 파싱할 수 있습니다. curl -s ... | jq '.choices[0].text'처럼 특정 필드만 추출할 수도 있습니다.

​
API 버전 관리 전략

1

URL 경로 방식 (가장 일반적)

/v1/models, /v2/models처럼 URL에 버전을 명시합니다. 직관적이고 캐싱이 쉬워서 대부분의 AI/ML API가 이 방식을 사용합니다.
2

헤더 방식

Accept: application/vnd.api+json; version=2처럼 헤더로 버전을 전달합니다. URL이 깔끔하지만 디버깅이 어려울 수 있습니다.
3

하위 호환 원칙

기존 필드를 삭제하거나 타입을 변경하지 않습니다. 새 필드 추가는 허용하되, 기존 클라이언트가 무시할 수 있도록 설계합니다.
4

Deprecation 정책

구 버전 종료 최소 3개월 전에 공지하고, 응답 헤더에 Sunset 날짜를 포함합니다.
아닙니다. 멱등성이 없는 POST를 단순 재시도하면 중복 작업이 생길 수 있습니다. Idempotency-Key 헤더 또는 작업 상태 확인 API를 함께 설계하세요. 지수 백오프(Exponential Backoff)와 최대 재시도 횟수를 반드시 설정합니다.
4xx는 입력/권한 문제라 클라이언트 수정이 필요합니다. 5xx는 서버 문제라 운영자 대응이 필요합니다. 이 구분이 없으면 장애 대응 우선순위가 무너집니다. 알림 시스템에서 5xx만 즉시 알림으로 설정하는 것이 일반적입니다.
성공률, p95 지연시간, 타임아웃 비율, 5xx 비율을 먼저 보세요. 기능 수보다 API 품질 지표가 운영 안정성을 결정합니다.
LLM API는 응답 시간이 수 초~수십 초로 길어 일반적인 타임아웃(5초)이 부족합니다. 스트리밍 응답(stream: true)을 활용하면 첫 토큰 도착 시간(TTFT)을 줄일 수 있습니다. 토큰 사용량 기반 과금이므로 max_tokens 설정과 비용 모니터링이 필수입니다.

​
체크리스트

  • API 스키마와 에러 코드가 문서화되어 있나요?
  • 타임아웃/재시도/백오프 정책이 있나요?
  • API 변경 시 하위 호환 전략이 있나요?
  • 상태 코드별 대응 주체(클라이언트/서버)가 정의되어 있나요?
  • LLM API 호출 시 스트리밍과 토큰 제한이 설정되어 있나요?

​
다음 문서