연동 담당이 말합니다. "프론트에서 CORS 에러 나고, Access Token이 만료됐는데 Refresh가 안 돌아요. 결제는 멱등키 없이 재시도해서 중복됐고요. SSO는 SAML Assertion 검증에서 막혔어요." PM·인프라인 당신은 각 문제가 어느 영역이고 누구에게 무엇을 물어야 하는지 판단해야 합니다. 이 사전은 API 연동·인증 용어를 빠르게 해독해, 연동 장애의 방향을 잡게 합니다.
- 1REST/GraphQL·HTTP 메서드·직렬화 용어로 API 구조를 읽을 수 있다
- 2토큰·JWT·OAuth/OIDC/SAML·SSO로 인증 흐름을 구분할 수 있다
- 3CORS·CSRF·SameSite로 브라우저 보안 이슈를 진단할 수 있다
- 4멱등성·레이트리밋·재시도로 연동 안정성 용어를 이해할 수 있다
API 형태와 요청 구성
REST/GraphQL과 요청의 부품들
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| REST API / SOAP / GraphQL | 대표 API 스타일 | REST/GraphQL → [[api-contract]] | ★★ |
| Endpoint | 호출 주소(경로) | 자원 단위 | ★★ |
| HTTP Method (GET/POST/PUT/PATCH/DELETE) | 행위 | GET=조회(안전) | ★★ |
| Header / Body / Payload | 메타정보 / 본문 / 전송데이터 | 인증·형식은 헤더 | ★★ |
| Query Parameter / Path Variable | ?key=값 / 경로 변수 | 조회 조건 vs 자원 id | ★★ |
| Content-Type / Accept | 보내는/받는 형식 | application/json 등 | ★★ |
| Multipart / Form Data | 파일·폼 전송 형식 | 업로드 | ★ |
| JSON / XML | 데이터 표현 형식 | JSON이 주류 | ★★ |
| Serialization / Deserialization | 객체↔전송형식 변환 | 직렬화 오류 단골 | ★★ |
| Schema Validation / JSON Schema / OpenAPI / Swagger | 형식 검증 / 계약 명세 | 계약 → [[api-contract]] | ★★ |
인증과 토큰
누구인지 확인하고 권한을 위임하는 용어
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Token / Access Token / Refresh Token | 인증 증표 / 짧은수명 / 재발급용 | 짧은 Access + 긴 Refresh | ★★★ |
| JWT | 서명된 토큰 형식(자체 정보 포함) | 검증이 서버 상태 불필요 | ★★ |
| OAuth / OAuth2 | 권한 위임 프로토콜 | "이 앱이 내 데이터 접근 허용" | ★★ |
| OIDC | OAuth2 위의 인증(로그인) 표준 | 신원 확인 | ★★ |
| SAML / SSO / ACS URL / SAML Assertion / Metadata XML | 기업 SSO(XML) 구성요소 | 사내 통합 로그인 → [[sso-saml-oauth]] | ★★ |
| Claim / Scope | 토큰 안 정보 / 권한 범위 | 인가 판단 | ★★ |
| Session / Cookie / SameSite | 세션 / 쿠키 / 교차요청 쿠키 정책 | 무상태 vs 세션 → [[twelve-factor-app]] | ★★ |
| CSRF Token / CORS | 위조요청 방지 / 교차출처 정책 | 브라우저 보안(아래) | ★★★ |
핵심: Access는 짧게·Refresh로 재발급이 표준. SSO 구성(SAML/OAuth)의 깊은 내용은 [[sso-saml-oauth]]에서.
브라우저 보안 — CORS·CSRF
자주 막히는 두 가지
CORS: 브라우저가 '다른 출처(origin)'로의 요청을 기본 차단
증상: 콘솔에 "blocked by CORS policy"
원인: 서버가 허용 출처를 응답 헤더(Access-Control-Allow-Origin)로 안 밝힘
대응: 서버에서 허용 출처/메서드/헤더 설정. (서버-서버 호출엔 무관)
CSRF: 로그인된 사용자의 권한으로 위조 요청을 보내는 공격
대응: CSRF 토큰, SameSite 쿠키 속성
핵심: CORS 에러는 브라우저 환경에서만 나는 클라이언트-서버 정책 이슈입니다. "백엔드는 되는데 프론트에서만 막힌다"면 CORS 1순위 의심. 서버 응답 헤더 설정으로 해결합니다.
연동 안정성 — 멱등·레이트리밋·재시도
중복과 과부하를 다루는 용어
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Idempotency / Idempotency Key | 중복 처리해도 결과 1번 / 그 키 | 결제·주문 필수 → [[requirements-prd]] | ★★★ |
| Rate Limit / Throttle | 호출 횟수 제한 / 속도 조절 | 429 응답 → [[glossary-observability]] | ★★ |
| Retry / Timeout | 재시도 / 시간 제한 | 멱등 없으면 재시도가 중복 유발 | ★★ |
| Webhook / Callback / Polling | 이벤트 푸시 / 콜백 / 주기 조회 | 연동 방식 → [[api-gateway-webhook]] | ★★ |
| API Gateway / Reverse Proxy | API 관문 / 역방향 프록시 | 라우팅·인증·레이트리밋 | ★★ |
핵심: 재시도(Retry)는 멱등성과 짝입니다 — 멱등 보장 없이 재시도하면 중복 결제가 납니다([[async-event-driven]]의 at-least-once와 동일 원리).
연동 에러 해독 — 직접 확인
연동 문제는 상태코드와 에러 메시지로 '어느 영역(인증/권한/형식/CORS)'인지 가릅니다.
# 인증 헤더와 함께 호출해 상태코드·헤더 확인
curl -i https://api.example.com/orders -H "Authorization: Bearer <token>"
HTTP/1.1 401 Unauthorized → 토큰 없음/만료 → Refresh로 재발급
HTTP/1.1 403 Forbidden → 인증은 됐으나 권한 없음(Scope/Role 부족)
HTTP/1.1 429 Too Many Requests → 레이트리밋 초과 → 백오프 후 재시도
(브라우저 콘솔) blocked by CORS → 서버 CORS 허용 설정 필요(브라우저만)
curl -i https://api.example.com/orders -H 'Authorization: Bearer <token>'- 401 Unauthorized → 토큰 없음/만료. Refresh Token으로 재발급 흐름이 동작하는지 확인. 반복되면 토큰 수명/시계 동기 문제
- 403 Forbidden → 인증은 됐는데 권한 부족(Scope/Role). 401과 구분: 401은 "누구인지 모름", 403은 "알지만 안 됨"([[glossary-saas-multitenant]]의 RBAC)
- 429 Too Many Requests → 레이트리밋 초과. 즉시 재시도 말고 지수 백오프. 우리가 과호출인지, 상대 한도가 낮은지 확인
- 브라우저 콘솔의 CORS 에러는 서버가 아니라 브라우저 정책 → 서버 응답 헤더(Allow-Origin) 설정. curl(브라우저 아님)로는 재현 안 됨에 주의
상황: 결제 요청이 타임아웃되자 클라이언트가 자동 재시도했는데, 사실 첫 요청은 서버에서 성공 처리된 상태라 결제가 두 번 일어납니다.
원인: 멱등성 미보장입니다. 재시도(Retry)는 안정성 기법이지만, 멱등 키 없이 하면 '같은 결제 두 번'이 됩니다([[async-event-driven]]의 중복 처리와 같은 함정).
진단:
□ 결제 요청에 Idempotency-Key 헤더가 있나?
□ 서버가 같은 키의 중복 요청을 한 번만 처리하나?
□ 타임아웃 후 재시도 정책이 멱등 전제 위에 있나?
해결: 결제·주문 같은 중요 API는 클라이언트가 Idempotency-Key를 보내고, 서버가 그 키로 중복을 흡수(이미 처리한 키면 기존 결과 반환)하게 합니다. 요구사항([[requirements-prd]])의 인수 기준에 "중복 요청 시 1건만 처리"를 명시하는 것이 출발점입니다. 재시도와 멱등은 항상 짝으로 설계합니다.
인프라/플랫폼으로서 API 게이트웨이·역방향 프록시에서 인증 검증·레이트리밋·CORS를 중앙 처리하고([[api-gateway-webhook]]), 토큰 검증·SSO 연동([[sso-saml-oauth]])을 운영합니다. 401/403/429의 구분은 대시보드 알람 설계의 기준이 됩니다([[glossary-observability]]). PM은 이 용어로 연동 요구사항을 명확히 적습니다 — "Idempotency-Key로 중복 방지", "Refresh 토큰 흐름", "허용 출처(CORS)" 같은 항목을 인수 기준에 넣어 연동 사고를 예방합니다. 외부 연동이 많은 서비스일수록 이 사전의 용어가 일상 언어가 됩니다.
다음 용어사전에서는 이 API가 도는 무대 — 서버·WAS·리눅스 운영 용어를 정리합니다.