엔드포인트 (Endpoint)

엔드포인트(Endpoint)는 프로그램이 네트워크를 통해 특정 기능이나 데이터에 접근하는 접점입니다. 웹 API에서는 보통 요청을 받는 URL이나 경로를 가리키며, 실제 동작을 구분할 때는 HTTP 메서드도 함께 봅니다. 같은 서버를 사용하더라도 사용자 목록 조회와 새 사용자 등록은 서로 다른 요청 계약을 갖습니다.

요청 주소와 메서드의 결합

GitHub의 REST API 시작 문서는 요청을 HTTP 메서드와 경로의 조합으로 설명합니다. 메서드는 조회나 생성처럼 수행할 동작을, 경로는 그 동작의 대상을 나타냅니다. 문서에 적힌 주소만 브라우저에서 열면 원래 의도한 요청과 메서드나 인증 정보가 달라질 수 있습니다. API 연결을 확인할 때 주소와 요청 형식을 함께 읽는 이유입니다.

사용자 정보를 다루는 API에서 GET /users를 목록 조회에, POST /users를 사용자 생성에 쓰면 경로 문자열은 같지만 서버가 처리하는 작업은 다릅니다. 엔드포인트라는 단어를 URL만 가리키는 좁은 뜻으로 쓰기도 하고, 메서드까지 포함한 개별 API 동작을 가리키는 뜻으로 쓰기도 하므로 문서의 표기 방식을 따라 해석합니다.

기본 주소는 여러 요청이 공유하는 서버 위치입니다. 여기에 기능별 경로를 붙여 요청 주소를 만듭니다. 개발 환경과 운영 환경의 기본 주소가 다르면 같은 경로를 사용해도 서로 다른 데이터에 접근합니다. 설정에서 주소를 바꿀 때는 모델명이나 함수 이름만 확인하는 것보다, 요청이 어느 환경의 서버에 도착하는지 확인하는 일이 먼저 필요합니다.

경로와 입력값의 경계

OpenAPI 명세의 Paths 정의는 개별 엔드포인트의 상대 경로와 그 경로에서 사용할 작업을 표현합니다. /users/{userId}의 중괄호 부분은 실제 사용자 식별자로 바꾸는 경로 매개변수입니다. 식별자를 채운 뒤의 주소는 특정 사용자를 가리킵니다. 명세의 자리 표시자를 실제 주소에 그대로 넣거나, 필요한 값을 빼면 서버가 의도한 자원을 찾지 못할 수 있습니다.

쿼리 매개변수는 주소 뒤에서 검색 조건이나 페이지 번호 같은 추가 입력을 전달합니다. 요청 본문은 생성할 데이터처럼 별도의 내용을 담고, 헤더는 인증이나 데이터 형식에 관한 정보를 전달합니다. 어떤 값을 어느 위치에 넣는지는 API가 정합니다. 같은 이름의 입력이라도 경로에서 요구하는 값을 본문에만 넣으면 계약을 만족하지 못합니다.

입력 형식과 응답 형식도 접점의 계약에 포함됩니다. JSON 요청을 받는 서버에 다른 형식의 내용을 보내거나 필수 필드를 빠뜨리면, 주소가 정확해도 처리가 실패합니다. SDK는 이 요청 구성을 함수 호출로 감싸 사용하기 쉽게 만듭니다. SDK 함수가 존재한다는 사실과 서버가 그 기능을 제공한다는 사실을 구분하면 버전 불일치가 생겼을 때 확인할 지점을 찾기 쉽습니다.

접근 권한과 실패 원인의 구분

HTTP 의미론 명세는 응답 상태 코드로 요청 처리 결과를 구분합니다. 인증이 필요하거나 권한이 부족한 경우, 자원을 찾지 못한 경우, 서버 처리에서 오류가 난 경우는 서로 다른 문제입니다. 다만 응답 앞단의 프록시나 보호 장치가 요청을 먼저 막을 수도 있으므로, 상태 코드 하나만으로 애플리케이션 내부 원인을 확정하지 않습니다.

공개된 엔드포인트 주소를 알고 있어도 호출 권한까지 생기는 것은 아닙니다. 서비스는 인증 토큰, 계정 권한, 호출 빈도 같은 조건을 적용할 수 있습니다. 연결 오류를 조사할 때는 요청 시각과 메서드, 비밀값을 제거한 경로, 응답 상태를 남기면 실패 구간을 좁히기 쉽습니다. 토큰이나 개인 데이터가 들어 있는 요청 전체를 공유 기록에 복사하면 조사 자료가 새 노출 경로가 됩니다.

재시도할 때도 요청의 의미를 봅니다. 조회 실패를 다시 요청하는 상황과 결제나 주문 생성을 다시 요청하는 상황은 중복 처리의 영향이 다릅니다. HTTP 명세가 정의하는 메서드의 성질에 더해, 해당 API가 중복 요청을 식별하는 방법을 제공하는지 확인합니다. 응답을 받지 못했다는 사실만으로 서버 작업이 실행되지 않았다고 판단하면 같은 작업을 두 번 만들 수 있습니다.