API

APIs 동기식 vs 비동기식

동기식 API

개념: 요청을 보내면, 응답이 돌아올 때까지 "멈춰서 기다리는" 방식.

쉽게 말해: 친구한테 카톡 보내고, 답장이 올 때까지 아무것도 안 하는 것과 같음.

장점: 흐름이 단순해서 이해하기 쉽다.

단점: 서버 응답이 늦으면 화면이 멈춘 것처럼 보여 불편하다.

예시:

• 은행 앱에서 송금 버튼을 눌렀을 때, 송금 성공 메시지를 받을 때까지 화면이 멈춤.
• 로그인할 때, 서버가 "맞는 아이디/비번"이라고 확인할 때까지 기다려야 다음 화면으로 넘어감.

비동기식 API

개념: 요청을 보내고, 응답을 기다리지 않고 다른 일을 하다가, 응답이 오면 따로 처리하는 방식.

쉽게 말해: 친구한테 카톡 보내고, 답장을 기다리는 동안 다른 앱을 쓰는 것과 같음.

장점: 프로그램이 끊기지 않고 여러 일을 동시에 할 수 있다.

단점: 코드를 짤 때 동기식보다 복잡해질 수 있다.

예시:

• 유튜브에 동영상을 업로드하면서, 업로드 완료를 기다리지 않고 다른 영상을 보는 것.
• 채팅 앱에서 메시지를 보내면 바로 채팅창에 보이지만, 서버 응답은 나중에 처리됨.

 

APIs 아키텍처 스타일

1. RPC (Remote Procedure Call)

개념: "원격 함수 호출". 내 코드에서 함수를 부르듯, 네트워크 너머 서버의 함수를 부르는 것.

쉽게 말해: 친구에게 "빵 사와"라고 말하면, 친구가 빵을 사서 가져다주는 느낌.

특징: 서버와 클라이언트가 같은 규칙(함수 이름, 매개변수)을 알아야 한다.

예시:

• gRPC: 구글이 만든 RPC 방식, 빠르고 성능이 좋다.

2. SOAP (Simple Object Access Protocol)

개념: XML을 쓰는 "엄격한 규칙의 메시지 봉투".

쉽게 말해: 정부 기관에 공식 문서를 보낼 때, 정해진 서식과 도장을 반드시 따라야 하는 것과 비슷.

특징: 보안, 트랜잭션(여러 작업을 하나처럼 처리) 기능을 기본 지원.

예시:

• 은행 간 계좌 이체 API.
• 보험사와 병원 간 데이터 연동.

3. REST (Representational State Transfer)

개념: HTTP와 URL을 활용하는 가장 대중적인 방식.

쉽게 말해: "웹 주소를 이용해 필요한 걸 요청"하는 것.

특징: 단순하고 가볍다. JSON을 주로 사용해 사람이 읽기 쉽다.

예시:

• GET /users/1/posts: 특정 사용자의 게시글 목록 가져오기.
• POST /products: 쇼핑몰에 새로운 상품 등록.

 

REST API 요청 & 응답

요청(Request)

구성 요소:

• URL: "어디에" 요청할지. 예: https://api.example.com/users/1
• 메서드: "무엇을 할지". (GET=조회, POST=생성, PUT=수정, DELETE=삭제)
• 헤더: 인증 정보, 데이터 형식 같은 추가 정보.
• 바디: 요청에 필요한 실제 데이터 (주로 JSON).

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Alice",
  "age": 30
}

 

응답(Response)

 

구성 요소:

• 상태 코드: 요청이 성공했는지 숫자로 알려줌 (200=성공, 404=없음, 500=서버 오류).
• 헤더: 응답의 추가 정보.
• 바디: 실제 결과 데이터.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 101,
  "name": "Alice",
  "age": 30
}

 

REST API 인증 & 권한 부여

목적

• 인증(Authentication): "너 누구야?" → 사용자의 신원을 확인.
• 권한 부여(Authorization): "너 뭘 할 수 있어?" → 사용자가 어떤 자원에 접근 가능한지 확인.

설명

• 로그인만으로 끝이 아님. → 어떤 사용자가 어떤 기능을 사용할 수 있는지 꼭 구분해야 한다.
• 보통은 토큰을 이용해서 보안 유지.

예시

API Key

• 간단한 비밀번호 같은 고유 키.
• 헤더에 추가해서 보냄.

GET /data HTTP/1.1
Host: api.example.com
Authorization: Api-Key abc123

 

OAuth2

• 구글/카카오 로그인 같은 방식.
• 인증 서버가 대신 신원을 보장해줌.

GET /profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...

 

JWT (JSON Web Token)

• 로그인 성공 시 토큰을 발급받음.
• 이 토큰 안에 사용자 정보와 권한이 들어있음.
• 이후 요청마다 토큰을 보내면 서버가 검증.

 

전체 요약

• 동기식 vs 비동기식: "답 올 때까지 기다리기" vs "답 기다리지 않고 다른 일 하기".
• RPC, SOAP, REST: 원격 함수 호출 vs 엄격한 XML 문서 vs 단순한 웹 주소 요청.
• REST API 요청/응답: HTTP 주소, 메서드, 상태 코드, JSON 중심.
• 인증/권한 부여: 로그인 확인 + 접근 권한 확인, 보통 토큰을 이용해 처리.

 

API Rate Limits

 

정의: 일정 시간 단위 내에 사용자나 애플리케이션이 API에 보낼 수 있는 요청 수를 제한하는 기법.

필요성:

• 서버 과부하 방지 (예: 금융기관의 계좌 조회 API가 동시에 수만 건 요청을 받으면 서버 다운 위험)
• 모든 사용자에게 공평한 서비스와 응답 시간 제공 (예: 공공기관 민원 시스템에서 한 사용자가 API를 독점하지 못하도록 보장)
• DoS(Denial-of-Service) 공격 방어 (예: 악의적인 봇이 과도한 요청을 보내 서비스 마비를 일으키는 것 차단)

1) Rate Limit 알고리즘

Leaky Bucket (누수 버킷)

• 모든 요청은 큐에 들어가고, 서버는 고정된 속도로 큐에서 요청을 처리.
• 큐가 가득 차면 새로운 요청은 거부됨.
• 예시: 카드사 승인 서버에서 결제 요청이 몰려도 일정 속도로 처리하여 안정성을 확보.
• 특징: 요청 폭주 방지, 하지만 지연·거부 발생 가능.

Token Bucket (토큰 버킷)

• 사용자에게 일정 시간 단위마다 토큰이 지급됨.
• 요청 1개당 토큰 1개 사용, 토큰 없으면 요청 거부.
• 토큰은 누적 가능 → 일정 시간 요청을 안 하면 이후 한꺼번에 많은 요청 가능.
• 예시: 클라우드 API(예: AWS S3)에서 일정 시간 동안 사용하지 않은 요청 권한이 누적되어 대량 파일 업로드 가능.
• 특징: 유연성이 높으나, 토큰 관리 및 재시도 로직 필요.

Fixed Window Counter (고정 창 카운터)

• 일정 시간 창에 요청 수를 카운터로 제한.
• 제한 도달 시 해당 시간 창 내 모든 추가 요청 거부.
• 다음 시간 창 시작 시 카운터 초기화.
• 예시: SNS 플랫폼(예: Twitter API)에서 15분 단위로 최대 요청 수를 제한해 스팸 방지.
• 특징: 단순하지만 사용하지 않은 요청은 누적 불가.

Sliding Window Counter (슬라이딩 윈도우 카운터)

• 최근 N초 동안 요청 수를 계산.
• 예: 1분에 5개 요청 가능 → 최근 60초 동안 5개 이미 요청했다면 추가 요청 거부.
• 예시: 실시간 주식 거래 API에서 사용자가 순간적으로 요청을 몰아 보내더라도 최근 1분 기준으로 제어.
• 특징: 시간 창 경계 문제 해결, 실시간 기반 제어.

 

2) Rate Limit 확인 방법

API 문서에서 제공되거나 응답 헤더에 포함됨.

대표적인 헤더 키:

• X-RateLimit-Limit: 지정 시간 단위 내 최대 요청 수
• X-RateLimit-Remaining: 현재 창에서 남은 요청 가능 수
• X-RateLimit-Reset: 제한이 초기화되는 시간

예시: GitHub API는 X-RateLimit-Limit과 X-RateLimit-Remaining을 명시하여 개발자가 현재 요청 가능량을 알 수 있음.

 

3) Rate Limit 초과 시 동작

서버는 요청 거부 및 에러 응답 반환.

일반적인 HTTP 상태 코드:

• 429 Too Many Requests
• 403 Forbidden

예시: 클라우드 보안 API 호출 시 초과하면 429 코드를 반환하고, Retry-After 헤더로 재시도 대기 시간을 알려줌.

4) 요약

• Rate Limit 목적: 안정성, 공정성, 보안.
• 알고리즘 종류: Leaky Bucket, Token Bucket, Fixed Window, Sliding Window.
• 현업 적용: 금융(결제, 계좌조회), 공공기관(민원 시스템), 클라우드 서비스(AWS, GitHub, Twitter 등).
• 확인 방법: 응답 헤더 활용.
• 초과 시 대응: 요청 거부 + 상태 코드 반환, 클라이언트는 재시도 로직 필요.

 

Webhooks

 

정의: 웹훅은 특정 이벤트가 발생했을 때, 지정된 URL로 HTTP POST 콜백을 보내 애플리케이션에 알림을 전달하는 방식.

핵심 개념:

• Polling(반복 조회)과 달리 실시간 이벤트 전달 가능.
• 애플리케이션은 “이벤트가 발생하면 알려줘”라고 요청하고, 공급자는 이벤트 발생 시 곧바로 알림을 보냄.
• 서버와 클라이언트의 역할이 반전됨: 이벤트가 발생하면 서버가 클라이언트에 POST 요청을 보냄.

별칭: 역방향 API(Reverse API).

예시:

1. Cisco DNA Center: 네트워크 장비 장애 발생 시, DNAC가 등록된 URI로 HTTP POST 전송 → 앱은 JSON 객체를 받아 자동으로 대응.
2. Cisco Webex Teams: 특정 회의실에 메시지가 게시되면 웹훅이 자동으로 알림을 앱에 전달 → API 반복 호출 불필요.
3. 금융권: 결제 게이트웨이에서 결제 승인/실패 이벤트를 가맹점 서버로 실시간 전달.
4. 전자상거래: PayPal, Stripe 같은 결제 서비스가 주문 완료/환불 이벤트를 상점 애플리케이션에 즉시 전달.

 

Consuming a Webhook

필수 요구사항:

1. 애플리케이션은 항상 실행 중이어야 함 (HTTP POST 요청 수신 가능).
2. 애플리케이션은 웹훅 공급자에 URI를 등록해야 함.
3. 애플리케이션은 수신한 알림 데이터를 처리할 수 있어야 함.

개발/운영 시 고려사항:

• 외부 서비스(3rd party)와 연동되므로, 정상 동작 확인이 어려울 수 있음.
• “웹훅 테스터” 같은 무료 온라인 도구를 활용하면 웹훅 알림 수신 및 데이터 미리보기 가능.

예시:

1. CI/CD 파이프라인: GitHub 웹훅 → 새로운 커밋 발생 시 Jenkins 서버로 POST 전송 → 빌드 자동 실행.
2. 보안 관제: 보안 솔루션이 이벤트(침입 탐지, 이상 징후)를 웹훅으로 보안 관제 서버에 전달.
3. 클라우드 모니터링: AWS CloudWatch 경보 → 특정 조건 발생 시 Lambda 함수로 POST 전송.
4. 메시징 서비스: Slack 웹훅 → 외부 시스템에서 특정 이벤트 발생 시 팀 채널로 알림 메시지 전송.

 

요약

• Webhook 장점: 실시간 알림, 불필요한 반복 요청 제거, 효율성 향상.
• Webhook 흐름: 공급자(event 발생) → 등록된 URI로 POST → 애플리케이션이 알림 처리.
• 예시: 네트워크 모니터링(Cisco DNAC), 협업툴(Webex, Slack), 금융 결제(PayPal, Stripe), DevOps(GitHub → Jenkins).