엔드포인트

엔드포인트는 웹 서비스에서 요청을 보낼 주소를 가리키는 말입니다. 네트워크 프로그래밍에서는 같은 말이 연결의 한쪽 끝을 가리킵니다. 보안에서는 네트워크에 붙는 노트북이나 휴대폰 같은 기기를 가리킵니다. 어느 분야의 글인지부터 갈라야 뜻이 정해집니다.

쉽고 빠른 이해

무슨 일을 하는 낱말인가 — 엔드포인트는 한 물건에 붙은 이름이 아닙니다. 웹 서비스 주소 https://dynamodb.us-west-2.amazonaws.com 도 엔드포인트입니다. 프로그램이 통신하려고 만드는 소켓도, 노트북 한 대도 엔드포인트라고 부릅니다.

왜 갈라 읽어야 하나 — 셋이 가리키는 것은 종류부터 다릅니다. 주소는 글자 한 줄입니다. 노트북은 기계입니다. 한 뜻으로 밀어붙여 읽으면 엉뚱한 것을 떠올리게 됩니다.

어떻게 가르나 — 글이 엔드포인트라고 부르는 것이 무엇인지를 봅니다.

주소 한 줄이면 웹 서비스 쪽 뜻입니다
연결에 참여하는 쪽이나 소켓이면 통신 쪽 뜻입니다
노트북이나 휴대폰 같은 기계 한 대면 보안 쪽 뜻입니다

대가 — 웹 서비스 안에서도 엔드포인트 하나를 세는 단위가 문서마다 다릅니다. 주소 하나를 하나로 세는 문서가 있습니다. 경로와 메서드를 묶은 한 줄을 하나로 보고 문서를 나눠 둔 쪽도 있습니다.

상세

엔드포인트가 가리키는 것은 맥락마다 종류부터 다릅니다. 이 절은 먼저 그 종류를 나눕니다. 그다음 웹 API(Application Programming Interface, 응용 프로그램 인터페이스) 맥락의 엔드포인트를 주소 한 줄부터 펼칩니다. 웹 API 는 프로그램이 네트워크 건너편 프로그램의 기능을 부르는 방법을 정해 둔 약속입니다.

웹 API 맥락에서 엔드포인트는 주소입니다. 통신 연결 맥락에서는 연결에 참여하는 한쪽 끝입니다. 보안 맥락에서는 기기입니다. 메시지 전달 서비스에서는 메시지를 받아 갈 수신처입니다.

글이 엔드포인트라고 부르는 것이 이 넷 가운데 어느 종류인지를 보면 그 글의 맥락이 정해집니다. 맥락마다 무엇을 가리키는지와 그 근거는 아래 「맥락별 뜻」 절의 표에 있습니다.

웹 API 맥락의 엔드포인트

같은 기계 안에서라면 다른 프로그램의 기능을 부르는 데 주소가 필요 없습니다. 함수 이름을 부르면 끝납니다. 기능이 네트워크 건너편에 있으면 부르는 쪽은 찾아갈 주소가 있어야 합니다.

웹 API 맥락에서 엔드포인트는 요청을 받는 그 주소입니다. 웹 서비스로 들어가는 입구의 주소라고 보면 됩니다. AWS(Amazon Web Services)의 데이터베이스 서비스 DynamoDB 주소가 그런 예입니다.

AWS 는 서비스를 리전(Region)이라 부르는 지역마다 나눠 내놓습니다. 미국 서부 오리건 리전의 DynamoDB 엔드포인트는 https://dynamodb.us-west-2.amazonaws.com 입니다.

AWS 서비스 대부분은 리전마다 엔드포인트를 하나씩 둡니다. 그 주소는 대개 아래 꼴입니다.

protocol://service-code.region-code.amazonaws.com

엔드포인트 주소가 요청 내용과 떨어져 있으면 요청은 두고 받는 쪽만 바꿀 수 있습니다. SDK(Software Development Kit, 소프트웨어 개발 도구 모음)와 AWS CLI(Command Line Interface, 명령줄 도구)는 리전마다 정해진 기본 엔드포인트를 알아서 씁니다. 다른 엔드포인트를 지정할 수도 있습니다.

아래 명령은 암호 키를 관리하는 서비스인 AWS KMS(Key Management Service)에 키를 하나 만들라고 요청합니다.

aws kms create-key --endpoint-url https://kms-fips.us-west-2.amazonaws.com

이 명령은 그 요청을 기본 엔드포인트 대신 --endpoint-url 에 적은 주소로 보냅니다. 요청 내용은 같습니다. 받는 주소만 바뀝니다.

주소 한 줄을 이루는 조각

엔드포인트 주소는 URI(Uniform Resource Identifier, 통합 자원 식별자) 한 줄로 적습니다. URI 는 자원을 가리키는 문자열의 표기 규칙입니다. 한 줄이 다섯 조각으로 나뉩니다.

foo://example.com:8042/over/there?name=ferret#nose

아래 표에 나오는 호스트는 네트워크에 붙어 요청을 받는 컴퓨터입니다. 포트는 한 호스트 안에서 어느 프로그램이 받을지를 가르는 번호입니다.

이 한 줄을 조각별로 가르면 아래와 같습니다. 표는 줄에 적힌 순서를 따릅니다.

조각	위 줄의 값	무엇을 정하나
스킴	`foo`	나머지를 어떤 규칙으로 읽을지
오소리티	`example.com:8042`	어느 호스트의 어느 포트로 갈지
경로	`/over/there`	그 호스트 안의 어느 자원인지
질의	`name=ferret`	물음표 뒤에 덧붙이는 값
프래그먼트	`nose`	자원 안의 어느 부분인지

엔드포인트 주소가 다섯 조각을 다 쓰지는 않습니다. 앞에서 본 DynamoDB 엔드포인트는 스킴과 오소리티뿐입니다. 경로가 없습니다.

같은 경로에 붙는 여러 메서드

HTTP(HyperText Transfer Protocol, 하이퍼텍스트 전송 프로토콜) 요청은 주소와 함께 메서드를 하나 싣습니다. 메서드는 그 주소에 무엇을 시킬지 고르는 낱말입니다. GET 은 읽어 오라는 뜻으로 씁니다. POST 는 새로 만들거나 처리를 맡길 때 씁니다.

한 경로에 메서드가 여럿 붙기도 합니다. GitHub 의 REST(Representational State Transfer, 표현 상태 전달) API 에서 /repos/{owner}/{repo}/issues 경로가 그렇습니다. 이 경로에 GET 을 보내면 저장소의 열린 이슈 목록이 돌아옵니다. POST 를 보내면 이슈가 새로 생깁니다.

경로는 하나입니다. 하는 일은 둘입니다. 이 둘을 엔드포인트 하나로 볼지 둘로 볼지가 문서마다 다릅니다. 아래 「이견」에서 그 갈림을 다룹니다.

역할 이름이 붙은 엔드포인트

엔드포인트에 맡은 일을 이름으로 붙이기도 합니다. OAuth 2.0 이 그런 예입니다. OAuth 2.0 은 한 프로그램이 다른 서비스의 자원에 접근할 권한을 받아 가는 절차를 정한 표준입니다.

OAuth 2.0 은 권한을 넘겨주는 절차에 엔드포인트 셋을 둡니다. 둘은 권한을 내주는 인가 서버에 있습니다. 하나는 권한을 받아 가는 클라이언트에 있습니다.

아래 표에는 낱말 셋이 새로 나옵니다.

자원 주인 — 자원에 대한 접근을 허락하는 쪽입니다. 대개 그 계정의 사용자입니다
인가 그랜트 — 자원 주인이 접근을 허락했다는 증명입니다
액세스 토큰 — 허락을 받은 클라이언트가 자원을 부를 때 내미는 값입니다

괄호 안의 MUST 는 표준이 반드시 그렇게 하라고 못 박은 것입니다. MAY 는 그래도 된다고 허용한 것입니다. MUST NOT 은 하면 안 된다고 못 박은 것입니다.

엔드포인트	어디에 있나	무엇에 쓰나
인가 엔드포인트	인가 서버	클라이언트가 자원 주인의 브라우저 같은 프로그램을 거쳐 자원 주인에게서 인가를 받는다
토큰 엔드포인트	인가 서버	클라이언트가 인가 그랜트를 액세스 토큰으로 바꾼다. 대개 클라이언트 인증을 함께 거친다. 요청은 `POST` 로만 보낸다(MUST)
리다이렉션 엔드포인트	클라이언트	인가 서버가 인가 그랜트를 담은 응답을 자원 주인의 브라우저 같은 프로그램을 거쳐 클라이언트로 돌려보낸다

인가 그랜트를 받아 내는 절차에는 갈래가 여럿 있습니다. 그 갈래 하나를 그랜트 방식이라고 부릅니다. 어느 그랜트 방식이냐에 따라 두 서버 엔드포인트를 다 쓰지는 않습니다. 갈래를 새로 더한 확장 그랜트 방식은 엔드포인트를 더 정할 수 있습니다(MAY).

인가 엔드포인트가 어디 있는지는 보통 그 서비스의 문서가 알려 줍니다. 그 주소에는 위에서 본 다섯 조각 가운데 질의를 담아도 됩니다(MAY). 프래그먼트는 담으면 안 됩니다(MUST NOT).

맥락별 뜻

엔드포인트가 맥락마다 무엇을 가리키는지를 넷으로 나눠 적습니다. 표의 「가리키는 대상」 칸을 견주면 맥락끼리 어디서 갈리는지 보입니다.

맥락	이 맥락에서의 뜻	가리키는 대상	출처
웹 API	웹 서비스로 들어가는 입구의 주소	주소 한 줄	AWS General Reference 「AWS service endpoints」 · API 를 기술하는 형식인 OpenAPI 3.1 의 Paths Object
통신 연결	통신을 위해 만드는 한쪽 끝. 연결에 참여해 패킷을 만들고 받고 처리하는 실체	소켓 · 연결의 참여자 · 요청을 받는 백엔드	POSIX(Portable Operating System Interface) 2024년 판의 `socket()` · RFC(Request for Comments) 9000 의 용어 정의 · Kubernetes 문서 「EndpointSlices」
보안	네트워크에서 디지털 신원에 접근하는 데 쓰는 기기	기기	NIST(National Institute of Standards and Technology, 미국 국립표준기술연구소) SP(Special Publication) 800-63-4 용어집
메시지 전달	메시지가 발행되는 채널을 구독해 받아 가는 수신처	이메일 주소 · 큐 · 함수 같은 수신처	Amazon SNS(Simple Notification Service) 개발자 안내서의 구독 대목

웹 API · 통신 연결 · 보안 셋이 가리키는 것은 서로 다른 종류입니다. 주소 문자열은 기기가 아닙니다. 노트북 한 대는 주소가 아닙니다.

웹 API 맥락은 위 「상세」에서 펼쳤습니다. 아래는 나머지 셋입니다.

통신 연결 맥락

통신 연결 맥락의 엔드포인트는 데이터가 오가는 연결의 한쪽 끝입니다. 소켓은 프로그램이 운영체제를 거쳐 데이터를 주고받으려고 여는 통신용 객체입니다. 프로그램은 소켓으로 이 끝을 만듭니다.

socket() 함수는 통신을 위한 엔드포인트 하나를 만듭니다. 만든 소켓을 가리키는 파일 디스크립터를 돌려줍니다.

파일 디스크립터는 운영체제가 열린 파일이나 소켓에 붙여 주는 0 이상의 정수입니다. 막 만든 소켓은 아직 어느 주소에도 묶이지 않은 상태입니다. 엔드포인트가 먼저 생기고 주소는 그다음입니다.

전송 프로토콜에서도 같은 말을 씁니다. 전송 프로토콜은 두 프로그램 사이에서 데이터를 실어 나르는 규칙입니다. UDP(User Datagram Protocol, 사용자 데이터그램 프로토콜)는 연결을 맺지 않고 데이터 묶음을 보내는 전송 프로토콜입니다.

QUIC(퀵)은 UDP 위에서 도는 전송 프로토콜입니다. 여러 데이터 흐름을 한 연결에 겹쳐 싣습니다. 암호화도 함께 합니다.

QUIC 에서 엔드포인트는 QUIC 연결에 참여하는 실체입니다. 패킷을 만들고 받고 처리하는 쪽입니다. 엔드포인트는 클라이언트와 서버 두 종류뿐입니다.

연결을 시작하는 쪽이 클라이언트입니다. 연결을 받아들이는 쪽이 서버입니다.

QUIC 에서 주소라는 말을 달리 한정하지 않고 쓰면 IP(Internet Protocol) 버전 · IP 주소 · UDP 포트 번호 셋을 묶은 값을 뜻합니다. 이 값이 네트워크 경로의 한쪽 끝을 나타냅니다. 엔드포인트는 연결에 참여하는 쪽입니다. 주소는 그 끝을 나타내는 값입니다.

flowchart TD
    subgraph CL["엔드포인트 · 연결을 시작하는 클라이언트"]
        C1["주소 · IP 버전 · IP 주소 · UDP 포트 번호"]
    end
    subgraph SV["엔드포인트 · 연결을 받아들이는 서버"]
        S1["주소 · IP 버전 · IP 주소 · UDP 포트 번호"]
    end
    CL -->|"연결을 시작한다"| SV

그림의 상자 둘이 엔드포인트입니다. 상자 안의 값이 주소입니다. 연결은 클라이언트 쪽 엔드포인트가 시작합니다.

쿠버네티스는 컨테이너를 여러 기계에 나눠 띄우고 관리하는 시스템입니다. 파드는 쿠버네티스가 컨테이너를 띄우는 단위입니다.

쿠버네티스의 서비스는 여러 파드를 한 이름으로 묶어 요청을 받게 하는 객체입니다. 서비스 뒤에서 요청을 받는 엔드포인트는 대개 파드입니다.

쿠버네티스에서도 엔드포인트와 주소는 갈립니다. 엔드포인트는 요청을 받는 그 파드입니다. IP 주소는 그 파드를 가리키는 값입니다.

EndpointSlice 는 이 엔드포인트들의 IP 주소를 들고 있는 객체입니다. 쿠버네티스에서는 이렇게 묶는 엔드포인트를 네트워크 엔드포인트라고도 부릅니다. 같은 것을 가리키는 두 이름입니다.

EndpointSlice 는 네트워크 엔드포인트를 IP 버전 · 프로토콜 · 포트 번호 · 서비스 이름이 같은 것끼리 묶습니다. 한 객체 안에 포트 80 과 주소 10.1.2.3 이 함께 적힙니다.

보안 맥락

보안 맥락의 엔드포인트는 기기입니다. 네트워크에서 디지털 신원에 접근하는 데 쓰는 기기라면 다 들어갑니다. 디지털 신원은 온라인에서 한 사람이나 주체를 나타내는 신원입니다.

노트북 · 데스크톱 · 휴대폰 · 태블릿 · 서버 · 사물인터넷 기기가 다 엔드포인트입니다. 가상 환경도 이 목록에 들어 있습니다. 손에 잡히는 기계만 가리키는 말은 아닙니다.

메시지 전달 맥락

메시지를 발행하고 구독하는 서비스에서는 메시지를 받아 갈 수신처를 엔드포인트라고 부릅니다. 토픽은 메시지를 발행하는 채널입니다. Amazon SNS 에서 토픽에 엔드포인트를 구독시키면 그 엔드포인트가 토픽에 발행된 메시지를 받기 시작합니다.

구독을 만들 때 엔드포인트 종류를 고릅니다. HTTP 나 HTTPS(HTTP Secure, 암호화를 더한 HTTP) · 이메일 · Amazon SQS(Simple Queue Service) · AWS Lambda(코드를 함수 단위로 실행하는 서비스) · 플랫폼 애플리케이션 엔드포인트 · SMS(Short Message Service) 가운데 하나입니다.

엔드포인트 칸에는 그 종류에 맞는 값을 넣습니다. 이메일 주소나 SQS 큐의 ARN(Amazon Resource Name, 아마존 자원 이름)이 그런 값입니다.

HTTP·HTTPS 엔드포인트와 이메일 주소, 다른 AWS 계정의 자원은 구독을 확인받아야 메시지를 받습니다. 이 맥락에서 엔드포인트는 주소일 수도, 큐일 수도, 함수일 수도 있습니다.

이견

웹 API 맥락 안에서도 엔드포인트 하나가 어디까지인지가 문서마다 다릅니다. 엔드포인트 하나를 세는 단위는 세 진영으로 갈립니다. 어느 쪽이 맞는지는 가리지 않습니다.

엔드포인트 하나의 단위	그렇게 쓰는 문서
서비스의 기반 주소 하나	AWS General Reference · Google AIP(API Improvement Proposals)-9 용어집
경로 하나. 메서드는 그 아래	OpenAPI 3.1 · RFC 6749 (OAuth 2.0)
메서드와 경로를 묶은 한 줄	GitHub REST API 레퍼런스

세 진영이 엔드포인트라고 부르는 층은 아래처럼 위아래로 쌓입니다. 기반 주소 뒤에 경로가 붙습니다. 경로 밑에 메서드가 매달립니다.

flowchart TD
    subgraph 층1["AWS · Google 이 엔드포인트라 부르는 층"]
        S["기반 주소 · 스킴과 오소리티"]
    end
    subgraph 층2["OpenAPI · RFC 6749 가 엔드포인트라 부르는 층"]
        P["경로 · /repos/{owner}/{repo}/issues"]
    end
    subgraph 층3["GitHub 레퍼런스가 엔드포인트 하나로 문서화하는 층"]
        G["GET · 이슈 목록"]
        Q["POST · 이슈 만들기"]
    end
    S --> P
    P --> G
    P --> Q

같은 이슈 경로를 두고 경로 하나로 세는 OpenAPI 식으로 보면 엔드포인트가 하나입니다. 메서드와 경로를 묶어 세는 GitHub 레퍼런스 식으로 보면 둘입니다.

서비스의 기반 주소 하나

AWS General Reference 는 엔드포인트를 AWS 웹 서비스로 들어가는 입구의 URL(Uniform Resource Locator, 인터넷 주소)이라고 적습니다. 오리건 리전의 DynamoDB 엔드포인트 https://dynamodb.us-west-2.amazonaws.com 에는 경로가 없습니다. 서비스와 리전을 짚는 주소까지가 엔드포인트 하나입니다.

Google AIP-9 용어집도 같은 층을 엔드포인트라 부릅니다. API 서비스가 들어오는 요청을 처리하려고 쓰는 네트워크 주소가 API service endpoint 입니다. 한 서비스가 https://pubsub.googleapis.com 과 https://content-pubsub.googleapis.com 처럼 엔드포인트를 여럿 둘 수 있습니다.

같은 용어집은 API 안의 연산 하나를 API method 라고 부릅니다.

경로 하나에 메서드가 매달린 것

OpenAPI 는 API 를 기술하는 문서 형식입니다. 서버 주소와 경로를 갈라 적습니다. 경로를 서버 주소 뒤에 이어 붙여 전체 주소를 만듭니다. 경로 하나를 「개별 엔드포인트로 가는 상대 경로」라고 부릅니다.

그 경로에서 쓸 수 있는 연산은 경로 아래에 적습니다. get · put · post · delete 같은 칸이 경로 하나에 매달립니다. 엔드포인트는 경로입니다. 메서드는 그 아래의 연산입니다.

OAuth 2.0 을 정한 RFC 6749 도 메서드를 엔드포인트 아래에 둡니다. 인가 엔드포인트는 HTTP 자원 하나입니다. 인가 서버는 여기에 GET 을 반드시 받아야 합니다(MUST). POST 도 받을 수 있습니다(MAY).

RFC 6749 가 엔드포인트라고 부르는 것은 스킴과 호스트까지 담은 주소 한 줄입니다. 경로 하나로 끊어 부르지는 않습니다. 메서드가 엔드포인트 아래에 붙는다는 모양만 OpenAPI 쪽과 같습니다.

메서드와 경로를 묶은 한 줄

GitHub REST API 레퍼런스는 엔드포인트를 하나씩 문서화합니다. 주로 다루는 자원별로 묶어 둡니다. 같은 경로 /repos/{owner}/{repo}/issues 의 GET 과 POST 가 「List repository issues」와 「Create an issue」라는 서로 다른 항목입니다.

두 항목은 각각 자기를 「This endpoint」라고 부릅니다. 메서드와 경로를 묶은 한 줄을 엔드포인트 하나로 센다고 못 박은 문장은 없습니다. 이 단위는 문서를 그렇게 나눠 둔 배치에서 읽힙니다.

그래서 「엔드포인트가 몇 개인가」는 어느 진영의 단위로 세는지를 먼저 정해야 답이 나옵니다.

경계

API 와 엔드포인트는 같은 것인가. 아닙니다. 엔드포인트를 어느 단위로 세든 엔드포인트 하나가 API 전체가 되지는 않습니다.

이 판정은 웹 API 맥락의 두 낱말을 놓고 「한쪽이 다른 쪽을 다 덮는가」로 잽니다. 「이견」의 세 진영을 하나씩 대 봅니다.

OpenAPI 문서 하나는 API 하나를 기술합니다. 그 맨 위의 paths 칸에 그 API 에서 쓸 수 있는 경로와 연산을 담습니다. 경로 하나가 엔드포인트 하나이니 API 하나에 엔드포인트가 여럿 달릴 수 있습니다.

GitHub REST API 는 엔드포인트를 주로 다루는 자원별로 묶어 둡니다. 이슈에 관한 엔드포인트가 한 묶음입니다. API 하나 안에 그런 묶음이 여럿 있습니다.

기반 주소를 엔드포인트로 치는 쪽에서도 둘은 갈립니다. API 서비스는 API 를 하나 이상 구현합니다. 네트워크 주소 하나 이상에 그 API 를 내놓습니다.

엔드포인트는 그 서비스가 요청을 받는 주소 하나입니다. API 자체가 아닙니다.