API 엔드포인트란?

API 엔드포인트는 API가 한 리소스에 대한 요청을 받는 특정 URL로, HTTP 메서드와 짝을 이루어 하나의 오퍼레이션을 정의하는 접점입니다. 뒤쪽 절은 대부분의 정의가 건너뛰는 부분이며, 고전적인 혼란을 해소합니다. GET /users/42와 DELETE /users/42는 주소를 공유하지만 서로 다른 엔드포인트입니다. 같은 문이라도 노크를 하느냐 열쇠를 돌리느냐에 따라 다르게 반응하는 것과 같습니다.

핵심 요약

API 엔드포인트 URL의 구조

실제 요청 URL의 모든 부분에 레이블을 붙였습니다. RFC 3986의 문법을 따릅니다:

GET https://api.example.com/v1/users/42/posts?status=published&limit=20

GET                      메서드 – 동작이며, 오퍼레이션 식별의 일부
https                    스킴 – TLS, 타협 불가
api.example.com          호스트      ┐ 기본 URL로, API의
/v1                      버전        ┘ 모든 엔드포인트가 공유
/users/42/posts          경로 – 리소스: 사용자 42의 게시물
        42               경로 파라미터 – "어떤" 리소스인지 식별
?status=published        쿼리 파라미터 – "어떻게" 반환할지 지정:
&limit=20                필터, 정렬, 페이지네이션 (식별에는 포함되지 않음)

애플리케이션 코드에서 엔드포인트를 호출하는 모습입니다. SDK가 URL, 메서드, 인증을 대신 조합합니다:

// JavaScript / Node.js — Back4app JS SDK
// Every class gets endpoints automatically — this call hits one
const query = new Parse.Query('Todo');
query.equalTo('done', false);
query.limit(10);
const todos = await query.find();
// Endpoint used: GET /classes/Todo?where={"done":false}&limit=10

// Flutter / Dart — Back4app Flutter SDK
// Every class gets endpoints automatically — this call hits one
final query = QueryBuilder<ParseObject>(ParseObject('Todo'))
  ..whereEqualTo('done', false)
  ..setLimit(10);
final response = await query.query();
// Endpoint used: GET /classes/Todo?where={"done":false}&limit=10

// iOS / Swift — Back4app Swift SDK
// Every class gets endpoints automatically — this call hits one
let query = Todo.query("done" == false)
  .limit(10)
let todos = try await query.find()
// Endpoint used: GET /classes/Todo?where={"done":false}&limit=10

// Android / Kotlin — Back4app Android SDK
// Every class gets endpoints automatically — this call hits one
val query = ParseQuery.getQuery<ParseObject>("Todo")
query.whereEqualTo("done", false)
query.limit = 10
val todos = query.find()
// Endpoint used: GET /classes/Todo?where={"done":false}&limit=10

엔드포인트 vs. API vs. URL vs. 라우트

어떤 상위 노출 페이지도 한 번에 제공하지 않는 네 갈래 구분입니다:

엔드포인트와 라우트는 같은 것을 양 끝에서 본 것입니다. 프레임워크는 라우트를 선언하고, 클라이언트는 엔드포인트를 호출합니다. 그리고 OpenAPI 명세가 전체 그림을 공식화합니다. API는 경로의 집합이고, 각 경로는 메서드를 키로 하는 오퍼레이션을 가지며, “이 API에는 엔드포인트가 몇 개인가?”라는 질문은 사실 오퍼레이션의 수를 세는 것입니다.

경로 파라미터 vs. 쿼리 파라미터

대부분의 설계 논쟁을 정리하는 규칙은 식별은 경로에, 조정은 쿼리에입니다:

이 구분에는 결과가 따릅니다. 경로 파라미터는 리소스의 식별(그리고 캐시 키)의 일부이고, 쿼리 파라미터는 표현의 모양을 정합니다. 쿼리 파라미터로만 도달할 수 있는 리소스(/getData?type=user&id=42)는 REST 성숙도 사다리가 출발하는 전형적인 0단계의 징후입니다.

엔드포인트 이름을 잘 짓는 법

소비자는 문서를 한 단어도 읽기 전에 엔드포인트 목록으로 API를 평가합니다:

엔드포인트 보호: 체크리스트

모든 엔드포인트는 문이며, 공격자는 잊힌 문까지 포함해 모든 문을 시도합니다. 압축한 체크리스트는 다음과 같습니다. HTTPS 전용, 모든 엔드포인트의 인증(인터넷에서 도달 가능한 “내부용” 예외 없음), API 단위가 아니라 리소스 단위의 인가(권한 부여). 사용자 42가 /users/43/orders를 읽는 것이 전형적인 객체 수준 인가 결함(broken object level authorization)입니다. 경로, 쿼리, 본문에 대한 입력 검증, 엔드포인트의 비용에 맞춘 속도 제한, 어떤 엔드포인트도 무제한 컬렉션을 반환하지 않도록 하는 상한이 있는 페이지네이션, 안전한 오류 응답(스택 트레이스 없음, 존재 여부 노출 없음)이 필요합니다. 그리고 팀들이 놓치는 하나가 목록 관리입니다. 문서화되지 않았거나 지원 중단되었는데도 살아 있는 “좀비” 엔드포인트는 OWASP API Security Top 10에 별도 항목으로 올라 있습니다. 기억하지 못하는 엔드포인트는 방어하지 못하는 엔드포인트입니다.

일반적인 사용 사례

엔드포인트 관점이 제값을 하는 곳입니다:

• 서드파티 API 소비 – 문서의 엔드포인트 목록이 곧 제품이며, 구조를 읽을 줄 아는 것이 그 목록을 읽는 방법입니다.
• 공개 API 설계 – 이름, 파라미터 위치, 버전 관리에 관한 결정은 소비자가 수년간 안고 살아갑니다.
• 연동 디버깅 – SDK 호출을 curl로 엔드포인트에 직접 보내는 요청으로 재현하면 클라이언트 결함과 서버 결함을 분리할 수 있습니다.
• 게이트웨이와 모니터링 구성 – 속도 제한, 알림, 접근 규칙은 엔드포인트 단위로 선언합니다.
• 보안 감사 – 엔드포인트 목록이 곧 공격 표면 지도이며, 감사는 이를 열거하는 것에서 시작합니다.

새 엔드포인트를 만들어야 할까? 결정 매트릭스

한계와 트레이드오프

• 엔드포인트 난립은 실제 부채입니다. 화면별, 팀별 엔드포인트는 쌓여 가며, 각각이 영원히 문서화, 테스트, 모니터링, 공격 표면의 대상이 됩니다. 잘 설계된 적은 수의 엔드포인트가 맞춤형 엔드포인트 여럿보다 낫습니다.
• 고정된 모양은 일부 소비자에게 맞지 않습니다. 엔드포인트는 정해진 것만 반환합니다. 이것이 바로 쿼리로 응답 모양을 정하는 API가 해결하려는 오버페칭/언더페칭 트레이드오프입니다.
• URL은 계약입니다. 엔드포인트 이름을 바꾸면 모든 소비자가 깨집니다. 마이그레이션은 버전 관리, 리디렉션, 지원 중단 일정을 뜻하므로, 오래 안고 갈 수 있는 이름을 설계해야 합니다.
• 일상 대화에서 메서드는 보이지 않습니다. “/users 엔드포인트”라고 하면 읽기인지 쓰기인지가 감춰집니다. 문서, 로그, 보안 규칙에서는 정확성이 중요합니다.
• 엔드포인트 수로는 품질을 가늠할 수 없습니다. 일관된 엔드포인트 12개를 가진 API가 즉흥적으로 만든 400개를 가진 API보다 나은 경우가 흔합니다. 품질의 신호는 양이 아니라 거버넌스입니다.

Back4app에서의 엔드포인트

Back4app은 관리형 데이터베이스, 자동 생성되는 REST 및 GraphQL API, 인증, 파일 스토리지, Cloud Code 서버리스 함수를 결합한 오픈소스 Backend as a Service(BaaS) 플랫폼입니다. 여기서 엔드포인트는 설계되는 것이 아니라 파생됩니다. Todo 클래스를 만들면 전체 메서드 세트를 갖춘 /classes/Todo와 /classes/Todo/:objectId가 즉시 노출되며(자동 생성 API 패턴), 사용자, 세션, 파일, 함수를 위한 기본 제공 엔드포인트도 함께 있습니다. 이들은 모두 하나의 기본 URL, 키 기반 인증, 클래스별 권한을 공유합니다. 코드 탭이 그 실질적인 결과를 보여 줍니다. SDK가 엔드포인트, 메서드, 자격 증명을 대신 조합하며, 위의 엔드포인트 체크리스트(일관된 이름, 모든 곳의 인증, 상한이 있는 쿼리, 좀비 없음)가 리뷰 시점의 규율이 아니라 플랫폼의 동작으로 주어집니다. 커스텀 오퍼레이션도 같은 방식으로 엔드포인트를 얻습니다. Cloud Code 함수를 배포하면 /functions/yourFunction이 생깁니다.