엔드포인트

엔드포인트는 프로그램이 다른 프로그램의 기능을 부를 수 있도록 열어 둔 창구입니다. 창구마다 붙은 주소 하나로 요청을 보내면 정해진 일이 일어납니다. 웹에서는 무엇을 시킬지와 어느 경로로 보낼지를 묶은 한 쌍이 창구 하나가 됩니다. 연결의 양쪽 끝을 가리키는 말로도 씁니다.

상세

도서관 카운터에 책 한 권을 올려놓기만 하면 직원은 아무 일도 시작하지 못합니다. 빌리러 왔는지 돌려주러 왔는지 말해야 무엇을 할지 정해집니다. 어느 책이냐와 무엇을 해 달라느냐가 함께 있어야 접수 한 건이 됩니다.

엔드포인트는 그 접수 한 건에 해당합니다. 서비스는 어느 주소에 무엇을 시키는지를 묶은 한 쌍마다 맡을 일을 붙여 둡니다. 그 한 쌍이 맞는 요청만 그 일로 넘깁니다.

API(Application Programming Interface, 응용 프로그램 인터페이스)는 프로그램이 다른 프로그램의 기능을 부르는 방법을 미리 정해 둔 약속입니다. 같은 기계 안이라면 함수 이름을 부르면 끝납니다. 기능이 네트워크 건너편에 있으면 이름만으로는 못 찾아갑니다.

그래서 부르는 쪽이 찾아갈 주소를 내줍니다. 그 주소가 엔드포인트입니다. 한 서비스는 대개 엔드포인트를 여럿 냅니다. 주문을 만드는 것과 주문을 읽는 것이 각각 따로입니다.

주소 한 줄을 이루는 조각

웹에서 엔드포인트는 URL(Uniform Resource Locator, 인터넷 주소 표기법) 한 줄과 요청 메서드 하나로 적힙니다. 요청 메서드는 그 경로에 무엇을 시킬지 고르는 낱말입니다.

POST https://api.example.com/v1/orders

이 한 줄은 네 조각으로 나뉩니다. 맨 앞의 POST 가 메서드입니다. 나머지가 주소입니다. 아래 표는 그 한 줄에 적힌 순서 그대로입니다.

https 는 웹에서 쓰는 전송 규칙인 HTTP(HyperText Transfer Protocol, 하이퍼텍스트 전송 규약)에 암호화를 더한 것을 가리킵니다.

https 와 호스트는 서비스가 어디 있는지를 가리킵니다. 경로와 메서드는 엔드포인트 하나를 다른 엔드포인트와 갈라 줍니다.

포트는 한 기계 안에서 어느 프로그램이 요청을 받을지를 가르는 번호입니다. 위 한 줄처럼 주소에 포트 번호가 안 보이면 규칙이 정해 둔 기본 포트로 갑니다.

경로와 메서드를 묶은 한 쌍

경로가 같아도 메서드가 다르면 다른 엔드포인트입니다. 서버는 둘을 함께 보고 어느 처리 코드로 넘길지 고릅니다.

GET    /orders/1024     // 주문 하나를 읽는다
POST   /orders          // 주문을 새로 만든다
DELETE /orders/1024     // 주문 하나를 지운다

세 줄에 경로는 둘뿐인데 엔드포인트는 셋입니다. /orders/1024 한 경로에 읽기와 지우기가 따로 걸려 있기 때문입니다.

flowchart TD
    subgraph 경로
        P1["/orders"]
        P2["/orders/1024"]
    end
    subgraph 처리코드["처리 코드"]
        H1["주문을 새로 만든다"]
        H2["주문 하나를 읽는다"]
        H3["주문 하나를 지운다"]
    end
    P1 -- POST --> H1
    P2 -- GET --> H2
    P2 -- DELETE --> H3

한 경로에서 화살표가 둘로 갈라지는 것이 엔드포인트가 경로보다 많아지는 까닭입니다.

이 한 쌍이 세는 단위이자 거는 단위입니다. 권한을 걸 때도, 부른 횟수를 셀 때도, 응답이 늦는 곳을 찾을 때도 이 단위로 봅니다.

요청이 엔드포인트에 닿기까지

주소를 적어 보낸 요청은 몇 손을 거쳐 처리 코드에 닿습니다. 부르는 쪽은 이 길을 몰라도 됩니다. 다만 요청이 엔드포인트에 안 닿을 때 어디를 봐야 하는지는 이 순서가 알려 줍니다. 서버 앞에는 요청을 먼저 받아 넘기는 앞단 장비가 한 대 섭니다.

flowchart TD
    C["부르는 쪽"] --> D["이름을 주소로 바꾼다"]
    D --> G["앞단 장비가 요청을 받는다"]
    subgraph 서버
        G --> R["메서드와 경로로 처리 코드를 고른다"]
        R --> H["주문을 만드는 처리 코드"]
    end
    H --> RES["응답을 돌려준다"]

이름을 주소로 바꾸는 일은 DNS(Domain Name System, 도메인 이름 체계)가 맡습니다. 바뀐 주소로 도착한 요청은 게이트웨이나 로드 밸런서 같은 앞단 장비가 먼저 받아 서버로 넘깁니다.

서버 안에서 메서드와 경로를 보고 처리 코드를 고르는 일을 라우팅이라고 합니다. 엔드포인트는 독립된 기계로 하나씩 돌지 않습니다. 한 서버가 여러 엔드포인트를 받아 라우팅으로 갈라 줍니다.

엔드포인트가 지는 약속

엔드포인트를 하나 열면 그 주소로 무엇을 보내야 하고 무엇이 돌아오는지가 약속이 됩니다. 이 약속이 흐리면 부르는 쪽은 매번 넣어 보고 나서야 무엇이 되는지 알게 됩니다.

보내는 쪽은 값을 싣는 곳이 셋으로 갈립니다. 하나는 /orders/1024 의 1024 처럼 경로에 박아 넣는 식별자입니다. 또 하나는 /orders?status=paid 처럼 주소 뒤에 물음표를 붙여 적는 질의 문자열입니다. 나머지 하나는 요청 본문에 싣는 값입니다.

돌아오는 쪽은 상태 코드 하나와 본문 하나입니다. 상태 코드는 요청이 어떻게 됐는지를 짧은 숫자로 알려 줍니다. 본문은 결과를 담습니다.

flowchart TD
    subgraph 보내는쪽["보내는 쪽"]
        A["경로 안의 식별자 · /orders/1024"]
        B["물음표 뒤의 질의 문자열"]
        C["본문에 싣는 값"]
    end
    subgraph 돌아오는쪽["돌아오는 쪽"]
        F["상태 코드"]
        G["본문"]
    end
    A --> E["엔드포인트"]
    B --> E
    C --> E
    E --> F
    E --> G

실패도 약속의 일부입니다. 어떤 실패에 어떤 답이 오는지를 안 적어 두면 부르는 쪽이 오류를 가려낼 수 없습니다.

엔드포인트를 가르는 두 방식

무엇을 엔드포인트 하나로 볼지는 설계하는 사람이 정합니다. 크게 두 갈래입니다.

하나는 다루는 대상마다 주소를 가르는 방식입니다. 주문과 회원과 결제가 각각 경로를 갖습니다. 무엇을 시킬지는 메서드가 맡습니다. REST(Representational State Transfer, 표현 상태 전달)가 이렇게 가릅니다.

다른 하나는 주소를 하나로 모으는 방식입니다. 주소는 하나뿐입니다. 무엇을 원하는지는 요청 본문에 적어 보냅니다. GraphQL이나 RPC(Remote Procedure Call, 원격 프로시저 호출) 계열이 이 모양입니다.

가르면 주소만 보고 무엇을 하는 요청인지 알 수 있습니다. 관문도 주소마다 따로 걸 수 있습니다. 모으면 요청 한 번으로 필요한 것을 한꺼번에 가져오는 대신, 무엇을 얼마나 시켰는지 재는 잣대를 따로 정해야 합니다.

엔드포인트마다 따로 거는 관문

엔드포인트 앞에는 요청을 거르는 관문이 여럿 섭니다. 이 관문은 대개 엔드포인트 단위로 겁니다.

인증은 부른 쪽이 누구인지 확인합니다. 접근 제어는 확인된 그 사람이 이 엔드포인트를 부를 수 있는지 봅니다. 속도 제한은 부른 횟수를 세어 넘치면 막습니다. 요청은 이 셋을 차례로 지나고 나서야 처리 코드에 닿습니다.

관문을 엔드포인트 단위로 거는 까닭은 엔드포인트마다 드는 비용과 위험이 다르기 때문입니다. 목록을 읽는 요청과 결제를 만드는 요청을 한 잣대로 묶으면 한쪽은 빡빡하고 다른 쪽은 헐거워집니다.

재는 것도 같은 단위입니다. 응답 시간과 오류율을 엔드포인트별로 나눠 봐야 어느 엔드포인트가 오래 걸리는지 보입니다. 전체를 한 덩이로 뭉쳐 보면 오래 걸리는 엔드포인트 하나가 평균에 묻힙니다.

한 번 연 주소를 바꿀 때

엔드포인트는 열리는 순간 부르는 쪽이 생깁니다. 경로 이름을 바꾸거나 돌려주는 값의 모양을 바꾸면 그 주소를 부르던 코드가 깨집니다.

그래서 바꿀 때는 옛 주소를 두고 새 주소를 따로 엽니다. 경로에 판 번호를 넣어 가르는 것이 흔한 방법입니다. 앞에서 본 /v1/orders 의 v1 이 그것입니다.

옛 주소는 닫기 전에 미리 알립니다. 부르는 쪽이 새 주소로 옮겨 갔는지 보고 나서 닫습니다.

stateDiagram-v2
    state "v1 만 열림" as S1
    state "v1 과 v2 가 함께 열림" as S2
    state "v1 을 닫겠다고 알림" as S3
    state "v1 닫힘" as S4
    [*] --> S1
    S1 --> S2 : 새 주소를 연다
    S2 --> S3 : 미리 알린다
    S3 --> S4 : 부르는 쪽이 다 옮겨 갔다

이렇게 옛 약속을 한동안 같이 지켜 주는 것이 하위 호환입니다.

같은 이름을 쓰는 다른 뜻

여기까지는 웹 API 의 엔드포인트였습니다. 같은 낱말을 다른 분야에서도 씁니다.

네트워크 쪽에서는 연결의 양쪽 끝을 엔드포인트라고 부릅니다. 인터넷에서 기계를 가리키는 주소와 포트 번호를 묶은 한 쌍이 그 끝 하나입니다. 프로그램은 소켓으로 이 끝을 잡고 데이터를 주고받습니다.

보안 쪽에서는 사람이 쓰는 노트북이나 휴대폰 같은 단말을 엔드포인트라고 부릅니다. 이 뜻만 주소가 아니라 기계를 가리킵니다.

셋은 통신의 끝을 가리킨다는 데서 뿌리가 같습니다. 어느 뜻인지는 문맥이 정합니다. 주소를 말하고 있으면 앞의 둘입니다. 기계를 말하고 있으면 마지막입니다.

관련 항목

엔드포인트 주소를 이루는 조각

URL · URI · 호스트 · 포트 · 경로 · 도메인 · 질의 문자열 · 식별자

엔드포인트를 부를 때 붙이는 요청 규칙

HTTP · 요청 메서드 · GET · HEAD · 안전한 메서드 · 멱등성 · 요청 대상 · 콘텐츠 협상 · 조건부 요청

엔드포인트가 돌려주는 응답과 그 값

상태 코드 · HTTP 403 · HTTP 429 · 표현 · 미디어 타입 · JSON · 페이로드

엔드포인트를 모아 내놓는 상위 구조

API · API 설계 · REST · GraphQL · gRPC · RPC · 웹소켓 · 서비스 · 마이크로서비스

요청을 엔드포인트까지 넘겨 주는 장비와 절차

DNS · 라우팅 · 게이트웨이 · 리버스 프록시 · 로드 밸런서 · 부하 분산 · 서비스 디스커버리 · IP 주소

엔드포인트 앞에서 요청을 거르는 관문

인증 · 접근 제어 · 속도 제한 · 스로틀링 · API 키 · 액세스 토큰 · 스코프 · CORS · 타임아웃 · 방화벽 · 공격 표면

엔드포인트 단위로 재는 지표

응답 시간 · 오류율 · 초당 요청 수 · 꼬리 지연 · 백분위수 · 관측성 · 감사 로그

엔드포인트를 바꿀 때 지켜야 하는 약속

하위 호환 · 시맨틱 버저닝 · 스키마 · API 버전 관리 · 계약 테스트 · 사용 중단

같은 이름을 쓰는 다른 분야의 개념

소켓 · 단말 · 전송 계층 · 커넥션 문자열 · 대상