엔드포인트(Endpoint) — API 요청이 정확히 향하는 주소

게시일 2026-04-30수정일 2026-04-30

On this page

API를 레스토랑이라면 엔드포인트는 메뉴별 주문 창구다. GET /articles는 글 목록 창구, POST /generate는 AI 생성 창구다. AI 서비스를 연동할 때 어떤 엔드포인트에 무엇을 요청하는지 이해하면 연동 난도가 절반으로 줄어든다.

정의

엔드포인트(Endpoint)는 API 요청이 도달하는 특정 URL 경로다. 서버가 외부에 공개하는 기능 단위로, HTTP 메서드(GET · POST · PUT · DELETE)와 URL 경로의 조합으로 정의된다.

api 통신에서 클라이언트는 어디로 요청을 보낼지 알아야 한다. 그 "어디"가 엔드포인트다. 서버는 내부 로직이 아무리 복잡해도 외부에는 정해진 URL 경로만 공개하며, 클라이언트는 그 경로를 통해서만 서버 기능을 사용할 수 있다.

rest 아키텍처에서는 엔드포인트가 리소스 중심으로 설계된다. /articles는 글 전체, /articles/{id}는 특정 글 하나를 가리킨다. HTTP 메서드가 행위를 결정하고, URL 경로가 대상을 결정하는 구조다.

AI API 엔드포인트 예시

주요 AI 서비스의 핵심 엔드포인트를 나란히 보면 공통 패턴이 드러난다.

# OpenAI
POST https://api.openai.com/v1/chat/completions    # 대화 생성
GET  https://api.openai.com/v1/models              # 사용 가능 모델 목록

# Anthropic (Claude)
POST https://api.anthropic.com/v1/messages         # 메시지 생성

# Google Gemini
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent

세 서비스 모두 POST 메서드로 생성 요청을 보낸다. URL 경로에는 /v1/ 같은 버전 prefix가 붙는데, 새 버전을 출시해도 기존 연동을 깨지 않기 위한 설계다. Anthropic이 /v1/messages를 /v2/messages로 바꾸기 전까지 기존 코드는 그대로 작동한다.

요청 시에는 엔드포인트 URL과 함께 인증 헤더(Authorization: Bearer <API_KEY>)와 JSON 본문이 필요하다. AI API는 대부분 model, messages, max_tokens 같은 공통 파라미터를 요청 본문에 담는다.

엔드포인트 설계 패턴

엔드포인트는 리소스와 행위의 조합으로 설계된다.

| HTTP 메서드 | 경로 | 의미 | |---|---|---| | GET | /articles | 글 목록 조회 | | GET | /articles/{id} | 특정 글 조회 | | POST | /articles | 새 글 생성 | | PUT | /articles/{id} | 특정 글 전체 수정 | | DELETE | /articles/{id} | 특정 글 삭제 |

AI 서비스 엔드포인트도 같은 원칙을 따른다. POST /v1/messages는 새 메시지(AI 답변)를 생성하는 행위다. GET /v1/models는 사용 가능한 모델 목록 리소스를 조회한다.

엔드포인트 설계에서 주의할 점은 동사 대신 명사를 쓰는 것이다. /createArticle 같은 동사형 경로는 REST 원칙에 어긋난다. 행위는 HTTP 메서드(POST)로 표현하고, 경로는 리소스(/articles)만 나타낸다.

활용 사례

AI 서비스 연동: Claude API나 OpenAI API 호출 시 엔드포인트 URL을 잘못 지정하면 404 Not Found가 반환된다. 버전이 올라가면서 deprecated된 엔드포인트(/v1/completions)를 계속 쓰는 경우 오류가 빈번하게 발생한다.

웹훅(Webhook) 수신: GitHub, Slack, Make.com 같은 외부 서비스가 이벤트 발생 시 서버의 특정 엔드포인트로 POST 요청을 보낸다. 서버는 해당 엔드포인트에서 요청을 수신하고 처리한다.

Rate Limit 관리: AI API는 엔드포인트별로 호출 횟수 제한(Rate Limit)을 다르게 설정한다. /v1/chat/completions와 /v1/embeddings의 분당 허용 호출 수가 다를 수 있으므로, 연동 전 공식 문서에서 엔드포인트별 한도를 확인해야 한다.

마이크로서비스 내부 통신: 여러 서비스로 분리된 백엔드 구조에서, 서비스 간 통신도 엔드포인트 호출로 이루어진다. 주문 서비스가 재고 서비스의 /v1/inventory/check 엔드포인트를 호출하는 방식이다.

정의

엔드포인트(Endpoint)는 API 서버에서 특정 리소스나 기능에 접근할 수 있는 고유한 URL 경로다. 클라이언트가 서버에 요청을 보낼 때 목적지가 되는 주소이며, 보통 HTTP 메서드(GET, POST, PUT, DELETE)와 함께 기능이 결정된다.

레스토랑으로 비유하면, API는 레스토랑 전체이고 엔드포인트는 각 메뉴별 창구다. "김치찌개 주세요"라고 하면 김치찌개 창구로 가야 하듯, "기사 목록을 주세요"라는 요청은 GET /articles 엔드포인트로 향해야 한다.

상세 설명

엔드포인트는 세 가지 요소로 구성된다.

베이스 URL: 서버의 기본 주소. 예를 들어 Anthropic의 Claude API라면 https://api.anthropic.com/v1이 베이스 URL이다.

경로(Path): 베이스 URL 뒤에 붙는 리소스 식별자. /messages, /models 등이 경로다. 계층 구조로 설계되어 /users/123/posts처럼 특정 사용자의 게시글만 가리킬 수도 있다.

HTTP 메서드: 엔드포인트에 어떤 동작을 요청하는지 결정한다.

GET — 데이터 조회. /articles는 글 목록을 돌려준다.
POST — 새 데이터 생성. /generate는 AI 생성 요청을 처리한다.
PUT / PATCH — 기존 데이터 수정.
DELETE — 데이터 삭제.

rest-api에서는 엔드포인트가 명사형 리소스 이름으로 구성되는 것이 관례다. /getArticles보다 GET /articles가 RESTful한 설계다.

예시

다음은 Claude API의 메시지 생성 엔드포인트를 호출하는 예시다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

여기서 엔드포인트는 https://api.anthropic.com/v1/messages이며, POST 메서드로 메시지 생성을 요청한다. 베이스 URL(https://api.anthropic.com/v1) + 경로(/messages)의 구조다.

OpenAI API라면 https://api.openai.com/v1/chat/completions가 해당 엔드포인트다. 서비스마다 경로 설계 방식이 다르므로, 공식 문서에서 엔드포인트 목록을 반드시 확인해야 한다.

활용 사례

AI 생성 요청: POST /v1/messages (Claude), POST /v1/chat/completions (OpenAI) — LLM에 텍스트 생성을 요청하는 핵심 엔드포인트
모델 목록 조회: GET /v1/models — 현재 사용 가능한 AI 모델 목록을 확인할 때 사용
이미지 생성: POST /v1/images/generations (OpenAI DALL·E) — 텍스트 프롬프트로 이미지를 생성
임베딩 변환: POST /v1/embeddings — 텍스트를 embedding 벡터로 변환. rag 파이프라인 구성에 필수
웹훅 수신: POST /webhook/callback — 외부 서비스가 이벤트 발생 시 내 서버로 데이터를 밀어주는 역방향 엔드포인트

엔드포인트(Endpoint) — API 요청이 정확히 향하는 주소

정의

AI API 엔드포인트 예시

엔드포인트 설계 패턴

활용 사례

관련 용어

정의

상세 설명

예시

활용 사례

관련 용어