API란 무엇인가?

API(Application Programming Interface)는 한 프로그램이 다른 프로그램의 기능을 사용할 수 있도록 정한 요청과 응답의 약속입니다.

식당에 비유하면 다음과 같습니다.

• 손님: 기능을 사용하려는 프로그램
• 주방: 기능을 실제로 처리하는 프로그램
• 메뉴판: 사용할 수 있는 기능과 주문 방법을 적은 API 문서
• 주문: API 요청
• 음식: API 응답

손님은 주방 내부의 조리 과정을 몰라도 메뉴판에 적힌 방법대로 주문하면 됩니다. 마찬가지로 클라이언트는 서버 내부 코드를 몰라도 API 규칙을 따르면 기능을 사용할 수 있습니다.

프론트엔드와 백엔드가 직접 서로의 내부 코드를 이해해야 한다면 변경할 때마다 두 프로그램을 함께 고쳐야 합니다. API라는 경계를 두면 각 프로그램은 약속만 지키면서 내부 구현을 독립적으로 바꿀 수 있습니다.

프론트엔드 ── 요청 ──> API ──> 백엔드 로직 ──> 데이터베이스
프론트엔드 <─ 응답 ─── API <── 처리 결과

API는 다음과 같은 곳에 쓰입니다.

• 웹·앱에서 서버의 회원, 상품, 주문 기능 사용
• 서로 다른 백엔드 서비스 간 통신
• 지도·결제·문자 같은 외부 서비스 사용
• 운영체제나 라이브러리가 제공하는 기능 사용

실무에서 “API를 호출한다”라고 하면 REST API를 떠올리는 경우가 많지만, API는 더 큰 개념입니다.

이 기술들이 항상 서로를 대체하는 경쟁 관계는 아닙니다. 한 서비스에서도 일반 CRUD에는 REST, 채팅에는 WebSocket, AI 답변에는 SSE, 내부 서비스 간 통신에는 gRPC를 함께 사용할 수 있습니다.

API를 사용하려면 최소한 다음 내용을 알아야 합니다.

1. 어디로 요청하는가?
2. 어떤 기능을 요청하는가?
3. 어떤 데이터를 보내는가?
4. 어떤 데이터가 돌아오는가?
5. 실패하면 어떻게 표현되는가?
6. 인증 정보는 어떻게 전달하는가?

REST API 예시는 다음과 같습니다.

GET /users/1
Authorization: Bearer access-token

{
  "id": 1,
  "name": "홍길동"
}

WebSocket API는 같은 목적을 메시지 이벤트로 정의할 수 있습니다.

{
  "type": "get_user",
  "userId": 1
}

표현은 다르지만 둘 다 양쪽 프로그램이 따라야 할 약속입니다.

두 개념은 다음처럼 구분합니다.

• API: 어떤 기능을 어떤 규칙으로 사용할지 정한 인터페이스
• 프로토콜: 데이터를 어떤 절차와 형식으로 주고받을지 정한 통신 규칙

HTTP와 WebSocket은 프로토콜입니다. REST는 HTTP를 활용하는 설계 스타일입니다. gRPC는 RPC 방식의 API를 만들기 위한 프레임워크입니다.

HTTP라는 통신 수단 위에 REST API를 만들 수 있다.
WebSocket이라는 통신 수단 위에 실시간 메시지 API를 만들 수 있다.

API 명세서는 클라이언트와 서버가 함께 보는 계약서입니다. 보통 다음 항목을 포함합니다.

• 기능 이름과 설명
• 요청 주소 또는 메서드
• 요청 데이터와 필수 여부
• 응답 데이터
• 오류 종류
• 인증 방법
• 실제 요청·응답 예시

REST API는 OpenAPI/Swagger를 많이 사용하고, GraphQL은 스키마, gRPC는 .proto 파일이 계약 역할을 합니다. WebSocket은 이벤트 이름과 메시지 구조를 별도로 문서화하는 경우가 많습니다.

API 설계 방식과 인증 방식은 별개의 문제입니다.

REST / GraphQL / gRPC
→ 기능과 데이터를 어떻게 요청할 것인가?

세션 / JWT / OAuth 2.0 / API Key
→ 요청한 사용자를 어떻게 확인할 것인가?

또한 API를 공부할 때는 HTTP, 캐시, CORS, 인증과 인가, 직렬화, 버전 관리도 함께 알아두면 좋습니다.

API는 프로그램끼리 기능을 사용하기 위한 약속이며, REST·GraphQL·gRPC·WebSocket 등은 그 약속을 구현하거나 전달하는 서로 다른 접근 방식이다.