[개념] API에 대해서 이해해보자!

서쿠·2025년 4월 27일

이미지 출처: https://appmaster.io/ko/blog/cobojareul-wihan-api-apireul-sayonghaneun-bangbeob-wanjeonhan-gaideu

1. API는 무엇인가?

💡 API는 애플리케이션 프로그래밍 인터페이스(Application Programming Interface)의 줄임말로,

소프트웨어 애플리케이션이 서로 통신하고 데이터나 기능을 교환할 수 있도록 하는 규칙이나 프로토콜을 의미합니다.

API를 통해 개발자는 다른 애플리케이션의 기능을 직접 구현하지 않고도 쉽게 활용할 수 있으며, 애플리케이션 개발을 간소화하고 효율성을 높일 수 있습니다.

과거에는 프로그램 간 직접 통신이 매우 어려워, 개발자가 수작업으로 일일이 대응해야 했습니다.

하지만 현재는 API를 통해 일정한 구조와 규약을 설정하고 통신할 수 있기에,
훨씬 효율적이고 체계적인 시스템을 구축할 수 있습니다.

🍔 비유하자면, API는 식당의 메뉴판 같은 것입니다:

고객이 메뉴판을 보고 주문하면, 주방은 정확하게 요청된 메뉴를 제공해줍니다.

또한, API를 사용하면

반복적인 코드 작성량을 줄이고,
사용자별 데이터 접근을 보다 안전하게 제어할 수 있으며,
내부 시스템 구축에도 활용할 수 있습니다.

즉, API는 개발 생산성과 보안성을 모두 향상시키는 핵심 수단이라고도 할 수 있을 것 같습니다.

2. API는 어떻게 작동하는가?

이미지 출처: https://assaeunji.github.io/development/2020-08-29-api/

API는 항상 요청(Request) 과 응답(Response) 구조를 따릅니다.

요청(Request): 클라이언트(사용자)가 서버에 필요한 정보를 요구하는 것.
응답(Response): 서버가 요청을 처리한 후 클라이언트에게 결과를 돌려주는 것.

이 과정은 주로 HTTP 통신 방식을 따르며,

GET(조회), POST(생성), PUT(수정), DELETE(삭제) 등의 메서드를 사용합니다.

응답 데이터는 대부분 JSON 형식을 통해 전달됩니다.

JSON (JavaScript Object Notation):

Key와 Value로 구성된 가볍고 직관적인 데이터 형식입니다.

API 통신 방식은 다음과 같이 다양한 유형이 존재합니다:

SOAP API: XML을 사용하여 엄격한 규칙 하에 통신하는 방식
RPC API: 서버의 함수를 원격으로 호출하여 응답받는 방식
WebSocket API: 실시간 양방향 통신을 지원하는 방식
REST API: 가장 널리 쓰이며 HTTP 기반으로 자원(Resource)을 주고받는 방식

🤔 최근 FAST API도 많이 보이는데, 이건 통신 방식이 아닌가?

FastAPI는 Python으로 API 서버를 쉽게 구축할 수 있게 해주는 웹 프레임워크입니다.

FastAPI는 API를 만드는 "도구(tool)"이지, '통신 프로토콜'이나 '통신 방식' 자체라고 볼 수는 없습니다.

💼 FastAPI를 통해 보통 사용하는 통신 방식은?

FastAPI를 이용해 만든 API 서버는 주로 RESTful API 통신 방식을 따르게 됩니다.

즉, HTTP 메서드(GET, POST 등)와 URI(통합자원식별자, Uniform Resource Identifier) 경로를 사용해서 통신하는 구조)

또한, FastAPI는 Python 기반이기 때문에, 비동기 통신(Async) 도 자연스럽게 지원하고, WebSocket 통신도 별도 설정으로 구축할 수 있습니다.

FastAPI 함수 예시:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, World!"}

-> 여기서 async def를 쓴 이유가 바로 비동기 처리를 위해서 def앞에 async를 사용함

async는 Python 3.5 버전부터 도입된 공식 문법으로, await와 쌍으로 사용됨.
- async def :이 함수는 '비동기적으로 실행될 수 있는 함수'. (Coroutine 생성)
- await : 이 함수 안에서, '어떤 비동기 작업'이 끝날 때까지 대기.

💿 음.. 비동기/동기 그게 뭔데

이미지 출처 : https://geekpython.medium.com/asyncio-how-to-use-async-await-in-python-ef4372a8c2c5

✔️ 동기 통신(Synchronous Communication)은,

요청(Request)을 보낸 다음, 응답(Response)이 올 때까지 "기다려야만" 다음 작업을 할 수 있는 방식입니다.
비유:
- 식당에서 음식을 주문하고, 음식이 나올 때까지 테이블에 앉아 기다리는 것. (나올 때까지 다른 일을 못 함)
Python 예시 (requests 사용):
```
import requests

response = requests.get('https://api.example.com/data')
print(response.text)  # 요청 끝날 때까지 기다린 다음 실행
```

✔️ 비동기 통신(Asynchronous Communication)은

요청(Request)을 보낸 뒤, "기다리지 않고" 바로 다음 작업을 처리하는 방식입니다.

비유:

식당에서 음식을 주문하고, 진동벨을 받아 자유롭게 돌아다니다가 벨이 울리면 음식을 받으러 가는 것. (기다리는 동안 다른 일을 할 수 있음)

Python 예시 (httpx 비동기 버전):


  import httpx
  import asyncio

  async def fetch_data():
      async with httpx.AsyncClient() as client:
          response = await client.get('https://api.example.com/data')
          print(response.text)  # 응답 준비되면 실행

  asyncio.run(fetch_data())

3. API 사용 시 꼭 확인해야 할 요소/팁

확인해야 할 요소

API 사용 시에 꼭 확인해야 할 요소는 다음과 같이 3가지가 있습니다:

Auth, HTTPS, CORS

Auth

설명: API 요청을 인증하는 방식 (apiKey, OAuth 등)
결론: 인증이 필요한 API는 반드시 키나 토큰이 필요합니다.

HTTPS

설명: 데이터를 암호화하여 안전하게 전송하는 프로토콜
결론: 민감한 정보를 다루는 경우 HTTPS는 필수입니다.

CORS

설명: 다른 출처의 웹사이트에서 API를 호출할 수 있도록 허용하는 설정
결론: 웹 프론트엔드에서 직접 API를 호출할 경우 CORS 정책을 고려해야 합니다.

이 항목들은 API를 안전하고 정상적으로 사용하기 위해 꼭 확인해야 합니다.

유용한 팁

public-api들을 리스트업 해서 정리·아카이빙해두는 좋은 깃헙 링크들 공유드립니다.

(영문) https://github.com/public-apis/public-apis
(한글) https://github.com/dl0312/open-apis-korea

다양한 Index(테마) 별로 API들을 확인할 수 있습니다.

4. 사용되는 다양한 API 형식

데이터 분석가나 과학자에게 API는 단순한 기술이 아니라, 데이터를 수집하고 분석 작업을 자동화하는 핵심 도구입니다.

다양한 API 형식이 존재하는 이유는

데이터의 성격
통신의 실시간성
데이터양과 응답속도 최적화

등을 고려하기 때문입니다.

각각을 조금 더 깊이 살펴봅니다.

[1] API "형식" (데이터 주고받는 구조)

REST API

출처 : https://stdio-han.tistory.com/88

개념: 웹상의 리소스를 URI로 식별하고 HTTP 메서드(GET, POST 등)를 통해 조작하는 가장 보편적인 방식.
포맷: 주로 JSON. (간혹 XML)
특징: 무상태성, 단순성, 범용성.
활용: 공공데이터포털, 주식, 기상청 데이터 수집.

GraphQL

출처 : https://www.wallarm.com/what/what-is-graphql-definition-with-example

개념: 클라이언트가 필요한 데이터만 명시적으로 요청할 수 있는 쿼리 기반 API.
포맷: 요청과 응답 모두 JSON.
특징: 단 하나의 Endpoint, 과요청/과소요청 문제 해결.
활용: GitHub, Shopify 등 복잡한 관계형 데이터 요청.

gRPC

출처 : https://www.oreilly.com/library/view/grpc-up-and/9781492058328/ch01.html

개념: Google이 개발한 초고속 이진 통신 프로토콜.
포맷: Protocol Buffers (바이너리 직렬화)
특징: 매우 빠름. 서버-서버 간 통신 최적화.
활용: 마이크로서비스 아키텍처, 초대용량 데이터 스트리밍.

JSON-RPC

출처: https://lab.wallarm.com/what/json-rpc%EB%9E%80-%EB%AC%B4%EC%97%87%EC%9D%B8%EA%B0%80/?lang=ko

개념: JSON 포맷을 기반으로 원격 함수 호출을 표준화한 프로토콜.
포맷: JSON.
특징: 가볍고 단순함.
활용: 내부 서비스 호출, 가벼운 서버 통신 (예: MCP).

[2] API "통신 프로토콜" (데이터를 어떻게 주고받을까?)

HTTP/HTTPS

개념: 웹 서버와 클라이언트 간 기본 통신 방식. HTTP는 비암호화, HTTPS는 암호화된 통신을 지원.
특징: 웹 API 대부분이 HTTP/HTTPS 기반으로 동작합니다.

출처 : https://han288.tistory.com/167

WebSocket

개념: 서버-클라이언트 간 양방향 통신을 지속적으로 유지할 수 있는 프로토콜.
특징: 연결이 한번 성립되면 계속 열린 채로 메시지를 주고받을 수 있어, 채팅, 게임, 실시간 데이터 전송 등에 최적화.

출처 : https://blog.algomaster.io/p/websockets

SSE (Server-Sent Events)

개념: 서버가 클라이언트로 단방향 실시간 스트리밍을 하는 통신 방식.
특징: 서버에서 클라이언트로만 이벤트를 지속적으로 푸시. HTTP 기반이라 브라우저에서 쉽게 사용 가능.

출처 : https://gong-check.github.io/dev-blog/BE/%EC%96%B4%EC%8D%B8%EC%98%A4/sse/sse/

SSE 특징 요약

항목	설명
통신 방향	서버 → 클라이언트 (단방향)
연결 방식	장시간 유지되는 HTTP 연결
인증 지원	JWT, API Key 인증 가능
용도	웹앱, 알림 시스템, 스트리밍 대시보드 등
예시	MCP Server C가 Remote Service와 연결할 때

STDIO (Standard Input/Output)

개념: 운영체제 수준의 표준 입력(stdin)과 표준 출력(stdout) 스트림을 이용한 통신 방식.
특징: 서버와 클라이언트가 같은 머신 안에서 동작하며, 파일처럼 데이터 스트림을 주고받습니다.

출처 ㅣ https://medium.com/@vkrishnan9074/mcp-clients-stdio-vs-sse-a53843d9aabb

STDIO 특징 요약

항목	설명
통신 방향	클라이언트 ↔ 서버 (양방향)
연결 방식	stdin/stdout 스트림
인증 지원	없음 (로컬 프로세스라 불필요)
용도	커맨드라인 툴, 로컬 테스트, 내부 통신
예시	MCP Server A, B와 Local Data 연결 시

🔥🔥 참고: 최근 핫한 MCP 서버는 STDIO, SSE 둘 다 지원합니다.

출처 : https://medium.com/@vkrishnan9074/mcp-clients-stdio-vs-sse-a53843d9aabb

STDIO 모드는 빠른 로컬 연결용 (ex: IDE, 로컬 툴)

SSE 모드는 네트워크 넘어 다수 클라이언트 연결용 (ex: 웹 기반 MCP 클라이언트)

[3] API 서버 구축 프레임워크

Python 기반

FastAPI: 초고속 비동기 API 서버. 타입 힌트 활용, OpenAPI 문서 자동 생성.
- https://fastapi.tiangolo.com/ko/
Flask: 매우 가볍고 단순한 API 서버 구축. 커스터마이징 유연함.
- https://flask.palletsprojects.com/
Django REST Framework: Django 기반 API 구축용 확장 라이브러리.
- https://www.django-rest-framework.org/

Node.js 기반

Express.js: Node.js에서 가장 대중적인 웹/REST API 서버 프레임워크.
- https://expressjs.com/ko/
NestJS: 대규모 백엔드 시스템을 위한 구조화된 Node.js 기반 프레임워크. TypeScript 지원.
- https://nestjs.com/

Java 기반

Spring Boot: 엔터프라이즈 급 웹/REST API 서버 구축에 가장 널리 사용되는 프레임워크.
- https://spring.io/projects/spring-boot

5. API 사용 범위에 따른 분류

구분	설명
Private API	기업 내부 전용, 외부에 공개하지 않음
Public API	누구나 사용할 수 있도록 공개된 API (ex. 날씨 API)
Partner API	특정 파트너 기업에만 제한적으로 제공되는 API
Composite API	여러 API를 결합하여 복합적인 데이터 처리 수행

이처럼 API는 용도에 따라 다양한 형태로 제공되며, 데이터 보안과 접근 통제 목적에 맞춰 설계됩니다.

6. Python으로 간단하게 API와 통신해 보자

예시1: Kakao 책 검색 API 사용하기

https://developers.kakao.com/docs/latest/ko/daum-search/dev-guide

import requests

url = "https://dapi.kakao.com/v3/search/book"

params = {
    "query": "파이썬",
    "sort": "accuracy",
    "target": "title"
}

headers = {
    "Authorization": "KakaoAK {REST_API_KEY}"
}

response = requests.get(url, params=params, headers=headers)

if response.status_code == 200:
    result = response.json()
    for book in result['documents']:
        print(f"제목: {book['title']}")
        print(f"소개: {book['contents']}")
        print(f"썸네일: {book['thumbnail']}\n")
else:
    print("API 요청 실패", response.status_code)

예시1 출력 결과

예시2: Kakao 웹문서 검색 API 사용하기

https://developers.kakao.com/docs/latest/ko/daum-search/dev-guide

import requests

# Kakao Web 문서 검색 API URL
url = "https://dapi.kakao.com/v2/search/web"

# 검색할 파라미터 설정
params = {
    "query": "이효리",       # 검색할 키워드
    "sort": "accuracy",      # 정확도순 정렬
    "page": 1,               # 1페이지
    "size": 10               # 한 번에 10개 문서 가져오기
}

# 인증 헤더 설정 (여기에 본인 REST API 키 넣어야 함)
headers = {
    "Authorization": f"KakaoAK {REST_API_KEY}"
}

# GET 요청 보내기
response = requests.get(url, params=params, headers=headers)

# 결과 처리
if response.status_code == 200:
    result = response.json()
    for doc in result['documents']:
        print(f"제목: {doc['title']}")
        print(f"본문 요약: {doc['contents']}")
        print(f"URL: {doc['url']}")
        print(f"작성일시: {doc['datetime']}\n")
else:
    print("API 요청 실패", response.status_code)

예시2 출력 결과

Python을 사용하면 이렇게 간단히 외부 API와 통신할 수 있으며, API 구조와 통신 흐름을 직접 체험할 수 있습니다.

또한 API 통합 시 고려해야 할 점은 다음과 같습니다:

데이터 모델(요청/응답 포맷)을 이해하고 설계해야 함
인증 방식과 권한 제어 로직을 명확히 설정해야 함
API 엔드포인트별 트래픽과 성능 이슈를 사전에 점검해야 함

7. FastAPI 간단 소개

⚡ FastAPI는 Python 3.6+ 이상 버전에서 사용할 수 있는 현대적이고 빠른 웹 프레임워크입니다.

주요 특징은 다음과 같습니다.

빠른 개발 속도: 타입 힌트를 사용해 코드 자동 완성과 문서 자동화
고성능: 비동기(Asyncio) 기반으로 빠른 응답 제공
자동 문서화: Swagger UI, Redoc 지원
Pydantic 기반 데이터 유효성 검사

간단한 FastAPI 코드 예시:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.post("/items/")
def create_item(item: dict):
    return {"item": item}

서버 실행:

uvicorn main:app --reload

main은 파일명, app은 FastAPI 객체명입니다.

마치며

이번 글에서는 API에 대해 정리하고, 다양한 API 통신 형식과 구축 프레임워크까지 살펴보았습니다.

데이터 분석가나 데이터 과학자에게도 API에 대한 이해는 점점 더 필요한 역량이 되고 있습니다.

특히 최근에는 MCP와 같이 JSON-RPC 및 SSE와 같은 통신 방식을 사용하는 프로토콜이 주목받고 있어, 새로운 트렌드를 따라가기 위해서라도 API 기본기를 다지는 것이 중요하다고 생각됩니다.

읽어주셔서 감사합니다 😎

서쿠

Always be passionate ✨

이전 포스트

내가 보려고 정리한 터미널 함수 25선

다음 포스트