API와 API 엔드포인트

한장희·2025년 9월 18일

API

API(Application Programming Interface)는 한 소프트웨어가 다른 소프트웨어의 기능을 사용할 수 있도록 연결해주는 인터페이스이다. 여기서 인터페이스는 서로 다른 두 개의 시스템이나 장치 사이에서 정보나 신호를 주고받는 '접점' 또는 '경계면'을 의미한다. API는 크게 웹 API, 운영 체제 API, 데이터베이스 API, 그리고 라이브러리/프레임워크 API로 나눌 수 있는데, 여기서는 웹 API에 대해서만 알아보겠다.

* DOM(Document Object Model)도 API의 한 종류이다. DOM은 웹 문서(HTML, XML)에 접근하고 조작할 수 있도록 도와주는 프로그래밍 인터페이스이자, 문서의 구조를 객체 트리 형태로 표현한 모델이다. DOM은 자바스크립트가 웹페이지의 요소들(태그 ,속성, 텍스트)을 객체로 인식하고, 이 객체들을 통해 요소를 조작가능하게 하는 인터페이스를 제공한다. 예를 들어, document.getElementById('id')에서 getElementById() 메소드가 DOM API의 한 부분이다.

API 엔드포인트

API 엔드포인트는 API가 특정 서비스나 리소스에 대한 요청을 수신하고 응답하는 특정 URL(Uniform Resource Locator)이다. 즉, 클라이언트가 서버와 통신할 수 있는 URL주소이다. 예를 들어, https://example.com/api/v1/resources와 같은 주소가 엔드포인트가 될 수 있다. 각 엔드포인트는 특정 기능을 수행하는 URL로, 클라이언트(웹 브라우저, 모바일 앱)는 이 엔드포인터에 요청을 보내고 서버는 그에 맞는 데이터를 반환하면서 데이터를 주고받는다. API 엔드포인트는 보통 RESTful API나 GraphQL API에 사용되고, 요청하는 리소스의 경로를 나타내는 URL과 함께 HTTP 메소드(GET, POST, PUT, DELETE, PATCH 등)를 사용하여 서버에 특정 작업을 요청한다.

<사전 개념>
리소스(Resource)는 웹에서 다루는 대상 객체(NoSql) 또는 엔터티(RDBMS)를 의미한다. 리소스는 데이터보다 더 큰 개념으로 데이터를 포함하는 대상이자 객체이다. 실제 데이터 뿐만 아니라, 데이터가 포함된 구조와 기능을 포함하는 더 넓은 개념이다.

서버에서 관리하는 대상 객체
데이터를 포함하지만 그자체가 엔티티를 의미한다. 예를 들어, 사용자(User)는 하나의 리소스이고, 게시글(Post)는 또 다른 리소스이다.
Resutful API에서 각 리소스는 고유한 URL(엔드포인트)을 가진다.
/users -> "사용자"라는 리소스를 다루는 엔드포인트
/posts -> "게시글"이라는 리소스를 다루는 엔드포인트

엔테티(Entity): 데이터베이스의 테이블에 저장된 행(row) 하나하나를 엔티티라고 부른다. 엔티티는 고유한 식별자(ID)를 가지며, 여러 개의 속성(컬럼)을 가질 수 있다.

데이터는 리소스의 내용을 의미한다. 즉, 리소스에 포함된 구체적인 정보가 바로 데이터이다. 데이터는 리소스가 가지는 속성이나 값을 나타내는 실제 정보이다.

리소스에 대한 구체적인 값
예를 들어, /users 리소스에서 id, name, email 등이 데이터이다. 이 데이터 들은 리소스인 "사용자"가 가진 속성들이다.
예시) 리소스 /users의 데이터:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

엔드포인트와 HTTP 메소드

GET(데이터 조회)
데이터를 조회할 때 사용된다. 서버에서 리소스를 읽어오는 요청.
POST(데이터 생성)
데이터를 서버에 전송하여 새로운 리소스를 생성할 때 사용한다.
PUT(리소스 전체 수정)
서버에 존재하는 리소스를 업데이트할 때 사용된다. 주로 리소스를 전체적으로 덮어쓰는 방식으로 수정한다.
PATCH(리소스 부분 수정)
리소스의 일부를 업데이트할 때 사용된다.
DELETE(데이터 삭제)
서버에서 리소스를 삭제할 때 사용된다.
HEAD(헤더만 조회)
GET과 유사하지만, 응답 본문(body)을 제외한 헤더정보만 반환한다. 주로 메타데이터를 확인할 때 사용한다.

메타데이터란 데이터에 대한 데이터이다. 데이터의 속성, 구조, 상태 등을 나타내며, 실제 데이터의 내용은 포함하지 않고, 그 데이터를 이해하고 활용하는 데 필요한 부가 정보를 제공한다. 예시) 1. 파일 메타데이터: 파일 크기, 파일 형식, 생성 날짜, 수정 날짜, 해상도 2. 웹 페이지 메타데이터: 페이지를 설명하고나, SEO를 돕기 위한 정보. 3. API에서의 메타데이터: 헤더를 통해 페이징 정보, 컨텐츠 타입, 최종 수정일, 서버 상태 코드등을 제공. 예시) Content-Type:데이터의 형식(예:application/json), Content-Length:응답 데이터 크기

엔드포인트 구성

https://example.com/api/v1/resources
- https:// :프로토콜
- example.com: 서버의 도메인 이름
- /api: API 관견 경로
- /v1: api 버전 정보
- /resources: 리소스를 나타내는 경로

리소스와 엔드포인트

Restful API에서 엔드포인트는 리소스를 나타낸다. 리소스는 서버에서 관리하는 데이터나 객체로 "사용자", "게시글", "댓글" 등이 될 수 있다.

단일 리소스: 특정 리소스를 나타내는 엔드포인트는 /resource/{id}형식이다. 특정 사용자의 정보를 조회하는 엔드포인트는 /users/{id}이다.
전체 리소스: 여러 리소스를 나타내는 엔드포인트는 /resources 형식이다. 모든 사용자의 목록을 조회하는 엔드포인트는 /users이다.

엔드포인트 설계 원칙

RESTful 원칙: 엔드포인트는 명사로 정의되며, HTTP 메소드로 동작을 정의한다.
리소스 명확화: 엔드포인트의 이름은 직관적으로 리소스를 나타내야 한다. /users는 사용자를, /posts는 게시글을 나타내야 한다.
버전 관리: v1,v2 등을 URL에 포함시켜 버전을 관리하고, 버전이 달라짐에 따라 호환성을 유지한다.

쿼리 파라미터(Query Parameters)

URL 경로 외에도, 요청에 추가적인 정보나 조건을 제공하기 위해 쿼리 파라미터를 사용할 수 있다.

GET /users?age=30&country=KOREA

위 요청은 사용자 중에서 "나이가 30살이고, 국가가 KOREA"인 사용자를 조회하는 요청이다.

엔드포인트 보안

API 엔드포인트에 접근하기 위해 보안이 중요하다.

인증(Authentication): API 엔드포인트에 접근하기 위해 사용자 인증이 필요할 수 있다. 일반적인 방법은 API키, JWT(JSON Web Token), OAuth 등이 있다.
권한 부여(Authorization): 인증된 사용자가 특정 작업을 수행할 수 있는지 여부를 결정한다.