---
term: 'API 엔드포인트'
seoTitle: 'API 엔드포인트란? 구조, 예시, 모범 사례'
headline: 'API 엔드포인트란?'
slug: api-endpoint
category: api-realtime
shortDefinition: 'API 엔드포인트는 API가 한 리소스에 대한 요청을 받는 특정 URL로, HTTP 메서드와 짝을 이루어 하나의 오퍼레이션을 정의하는 접점입니다.'
relatedTerms:
  - api
  - rest-api
  - api-gateway-architecture
  - auto-generated-database-apis
contrastsWith:
  - api-gateway-architecture
aboutTerms:
  - 'Base URL'
  - 'Path Parameters'
  - 'Query Parameters'
faq:
  - question: 'API 엔드포인트를 쉽게 설명하면 무엇입니까?'
    answer: 'API가 한 리소스에 관한 요청을 받는 특정 URL입니다. 각 엔드포인트는 API로 들어가는 문 하나입니다. GET 메서드로 /users/42에 보내는 요청은 사용자 42의 데이터를 요구하고, 같은 경로에 DELETE를 보내면 삭제를 요구합니다. API가 건물 전체라면 엔드포인트는 주소가 붙은 그 건물의 문입니다.'
  - question: 'API 엔드포인트의 예시는 무엇입니까?'
    answer: 'https://api.example.com/v1/users/42입니다. 기본 URL(스킴, 호스트, 버전) 뒤에 리소스를 가리키는 경로가 붙습니다. 실제 사례로는 코드 호스팅 플랫폼의 /repos/OWNER/REPO 엔드포인트, 또는 Back4app 앱이 Todo 데이터 클래스에 대해 자동 생성하는 /classes/Todo 엔드포인트가 있습니다.'
  - question: 'API와 엔드포인트의 차이는 무엇입니까?'
    answer: 'API는 계약 전체, 즉 서비스가 노출하는 규칙, 리소스, 오퍼레이션의 집합 전부입니다. 엔드포인트는 그 안의 특정 접근 지점 하나입니다. 하나의 API는 많은 엔드포인트를 노출하며, API 문서는 대부분 그 엔드포인트의 목록입니다.'
  - question: '엔드포인트는 URL과 같은 것입니까?'
    answer: '정확히 같지는 않습니다. 엔드포인트는 URL로 표현되지만, URL은 주소일 뿐이고 엔드포인트는 그 주소가 가리키는 상호작용 지점입니다. 문서는 보통 기본 URL을 생략하고 엔드포인트를 경로로 표기하며, 엄밀히 말하면 그 주소에서의 오퍼레이션을 정의하는 데에는 HTTP 메서드도 포함됩니다.'
  - question: '같은 URL이 둘 이상의 엔드포인트가 될 수 있습니까?'
    answer: '그렇습니다. GET /users/42와 DELETE /users/42는 URL을 공유하지만 서로 다른 오퍼레이션입니다. 그래서 OpenAPI 표준은 API를 경로의 집합으로 모델링하고, 각 경로가 메서드를 키로 하는 여러 오퍼레이션을 갖게 합니다. 사람들이 "엔드포인트" 수를 셀 때 보통 뜻하는 것은 오퍼레이션입니다.'
  - question: '엔드포인트와 라우트의 차이는 무엇입니까?'
    answer: '관점의 차이입니다. 라우트는 서버 측 정의, 즉 프레임워크 안의 경로 패턴, 메서드, 핸들러 함수입니다. 엔드포인트는 그 라우트에 도달할 수 있는, 클라이언트가 보는 URL입니다. 같은 것을 요청의 양 끝에서 바라본 것입니다.'
  - question: 'API의 엔드포인트는 어떻게 찾습니까?'
    answer: '신뢰도 순으로 세 가지 방법이 있습니다. 모든 경로와 오퍼레이션을 열거하는 문서나 기계가 읽을 수 있는 OpenAPI 명세를 읽거나, 브라우저 개발자 도구의 네트워크 탭에서 fetch/XHR로 필터링해 실제 트래픽을 관찰하거나, curl과 API 클라이언트로 직접 호출해 동작을 확인합니다.'
  - question: 'API 엔드포인트는 어떻게 보호합니까?'
    answer: '모든 엔드포인트를 공격 표면으로 다뤄야 합니다. HTTPS 전용, 모든 라우트의 인증, 최소 권한으로 범위를 제한한 인가, 입력 검증, 속도 제한, 상한이 있는 페이지네이션, 내부 정보를 노출하지 않는 오류 메시지가 필요합니다. 그다음 목록을 관리해야 합니다. 잊힌 "좀비" 엔드포인트는 API 보안 실패의 대표적인 원인입니다.'
codeLanguages: [javascript, dart, swift, kotlin]
externalAuthorities:
  - name: 'RFC 3986 — URI: Generic Syntax'
    url: 'https://datatracker.ietf.org/doc/html/rfc3986'
  - name: 'RFC 9110 — HTTP Semantics'
    url: 'https://www.rfc-editor.org/rfc/rfc9110'
  - name: 'OpenAPI Specification — Paths and Operations'
    url: 'https://spec.openapis.org/oas/latest.html#paths-object'
  - name: 'OWASP API Security Top 10'
    url: 'https://owasp.org/API-Security/'
cta:
  title: '설계할 필요가 없었던 엔드포인트'
  text: 'Back4app에서 클래스를 만들면 그 REST 엔드포인트가 즉시 존재합니다. 리소스 URL, 메서드, 인증, 권한을 플랫폼이 처리하며, 데이터 모델 전체에 걸쳐 일관됩니다.'
  linkText: '무료로 시작하기'
  linkUrl: 'https://www.back4app.com/signup'
author: 'Back4app Engineering'
publishedDate: '2026-10-29'
translationKey: api-endpoint
---

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

## 핵심 요약

| 질문 | 답변 |
| --- | --- |
| 공식 | 기본 URL + 경로(+ 메서드) = 한 리소스에 대한 하나의 오퍼레이션 |
| API와의 차이 | API = 계약 전체 · 엔드포인트 = 그 안의 접근 지점 하나 |
| 경로 vs. 쿼리 | 경로는 *어떤* 리소스인지 식별 · 쿼리는 *어떻게* 반환할지 지정 |
| 이름 짓기 | 복수형 명사, 소문자, 얕은 중첩 – 동사는 메서드가 담당 |
| 보안 | 모든 엔드포인트가 공격 표면 – 잊힌 엔드포인트까지 포함 |

## API 엔드포인트 URL의 구조

실제 요청 URL의 모든 부분에 레이블을 붙였습니다. [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)의 문법을 따릅니다:

```text
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:**

```javascript
// 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
// 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
```

**Swift:**

```swift
// 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
```

**Kotlin:**

```kotlin
// 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. 라우트

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

| 용어 | 정의 | 누구의 어휘인가 |
| --- | --- | --- |
| API | 계약 전체: 모든 리소스, 오퍼레이션, 규칙 | 모두의 어휘 |
| 엔드포인트 | 접근 지점 하나 – 한 리소스에 대한 요청을 받는 URL(+ 메서드) | 소비자의 관점 |
| URL | 엔드포인트의 위치를 가리키는 주소 문자열([RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)) | 네트워크 통신의 관점 |
| 라우트 | 서버 측 정의: 경로 패턴 + 메서드 + 핸들러 코드 | 구현자의 관점 |

엔드포인트와 라우트는 같은 것을 양 끝에서 본 것입니다. 프레임워크는 라우트를 선언하고, 클라이언트는 엔드포인트를 호출합니다. 그리고 [OpenAPI 명세](https://spec.openapis.org/oas/latest.html#paths-object)가 전체 그림을 공식화합니다. API는 *경로*의 집합이고, 각 경로는 메서드를 키로 하는 *오퍼레이션*을 가지며, "이 API에는 엔드포인트가 몇 개인가?"라는 질문은 사실 오퍼레이션의 수를 세는 것입니다.

```mermaid
flowchart LR
  accTitle: 요청이 엔드포인트를 거쳐 리소스에 도달하는 방식
  accDescr: 메서드와 URL을 가진 클라이언트 요청이 API의 기본 URL에 도착하면, 경로와 메서드로 엔드포인트의 라우트에 매칭되고, 인증과 검증을 통과한 뒤, 핸들러가 기반 리소스에 작업을 수행하고 응답을 반환합니다.
  C["클라이언트<br/>GET /v1/users/42/posts"] --> B["API 기본 URL<br/>라우트 매칭: 경로 + 메서드"]
  B --> A["인증 · 검증<br/>속도 제한"]
  A --> H["핸들러<br/>(라우트의 코드)"]
  H --> R[("리소스:<br/>사용자 42의 게시물")]
  R --> H --> C
```

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

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

| 파라미터가 답하는 질문 | 위치 | 예시 |
| --- | --- | --- |
| *어떤* 리소스인가? | 경로 | `/users/42`, `/orders/2026-1187` |
| 어떤 *관련* 컬렉션인가? | 경로 | `/users/42/posts` |
| 결과를 필터링하는가? | 쿼리 | `?status=published` |
| 정렬하거나 페이지를 나누는가? | 쿼리 | `?sort=-createdAt&limit=20` |
| 선택적인 동작 조정인가? | 쿼리 | `?include=author&fields=title` |

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

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

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

| 관례 | 좋은 예 | 나쁜 예 |
| --- | --- | --- |
| 동사가 아니라 명사 – 동사는 메서드가 담당 | `POST /orders` | `POST /createOrder` |
| 복수형 컬렉션 | `/users`, `/users/42` | `/user/42` |
| 소문자, 하이픈 연결 | `/purchase-orders` | `/PurchaseOrders`, `/purchase_orders` |
| 얕은 중첩(한 단계) | `/users/42/posts` | `/users/42/posts/8/comments/3/likes` |
| 정책을 갖춘 버전 접두사 | `/v1/…` + 지원 중단 기간 | `/v1`을 예고 없이 깨뜨림 |
| 예측 가능한 패턴 | 모든 리소스에 같은 모양 | 리소스마다 제각각의 방언 |

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

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

## 일반적인 사용 사례

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

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

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

| 상황 | 답 |
| --- | --- |
| 새로운 종류의 리소스 | 새 엔드포인트(`/invoices`) |
| 같은 리소스, 더 좁은 결과 | 기존 엔드포인트 + 쿼리 파라미터 |
| 같은 URL, 다른 동작 | 같은 경로, 다른 메서드 |
| 화면 하나에 엔드포인트 다섯 개가 필요 | 복합 엔드포인트를 고려 – 단, 아래의 난립 참고 |
| 표현의 변형(필드, 형식) | 새 경로가 아니라 쿼리 파라미터나 콘텐츠 협상 |
| 모양이나 의미의 호환성을 깨는 변경 | 지원 중단 기간을 둔 새 버전 접두사 |

## 한계와 트레이드오프

- **엔드포인트 난립은 실제 부채입니다.** 화면별, 팀별 엔드포인트는 쌓여 가며, 각각이 영원히 문서화, 테스트, 모니터링, 공격 표면의 대상이 됩니다. 잘 설계된 적은 수의 엔드포인트가 맞춤형 엔드포인트 여럿보다 낫습니다.
- **고정된 모양은 일부 소비자에게 맞지 않습니다.** 엔드포인트는 정해진 것만 반환합니다. 이것이 바로 쿼리로 응답 모양을 정하는 API가 해결하려는 [오버페칭/언더페칭](/glossary/ko/overfetching-underfetching/) 트레이드오프입니다.
- **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](/glossary/ko/auto-generated-database-apis/) 패턴), 사용자, 세션, 파일, 함수를 위한 기본 제공 엔드포인트도 함께 있습니다. 이들은 모두 하나의 기본 URL, 키 기반 인증, 클래스별 권한을 공유합니다. 코드 탭이 그 실질적인 결과를 보여 줍니다. SDK가 엔드포인트, 메서드, 자격 증명을 대신 조합하며, 위의 엔드포인트 체크리스트(일관된 이름, 모든 곳의 인증, 상한이 있는 쿼리, 좀비 없음)가 리뷰 시점의 규율이 아니라 플랫폼의 동작으로 주어집니다. 커스텀 오퍼레이션도 같은 방식으로 엔드포인트를 얻습니다. Cloud Code 함수를 배포하면 `/functions/yourFunction`이 생깁니다.