API(Application Programming Interface)란? 🤔
API는 서로 다른 프로그램들이 소통하는 방법을 정의한 약속입니다.
API의 장점 ✨
-
효율성
1) 이미 만들어진 기능 재사용 ex) 카카오 지도- 직접 지도를 만들면 엄청난 시간과 비용이 들어요
- 카카오 지도 API를 사용하면 바로 지도 기능을 넣을 수 있죠
2) 개발 시간 단축 ex) 결제 시스템
- 결제 시스템을 처음부터 만들면 몇 달이 걸려요
- 카카오페이 API를 사용하면 하루만에도 결제 기능 추가 가능!
-
일관성
1) 표준화된 데이터 교환 ex) 날씨 정보- 서울: 23도, 맑음
- 부산: 25도, 흐림
→ 모든 도시의 날씨 정보가 같은 형식으로 제공됨
2) 안정적인 서비스 제공 ex) 네이버 로그인
- 수많은 사이트에서 같은 방식으로 네이버 로그인 사용
- 한번 만들어진 방식이 계속 유지됨
-
보안성
1) 직접적인 데이터베이스 접근 방지 ex) 은행 계좌 조회- 계좌 정보가 있는 DB에 직접 접근하면 위험
- API를 통해 필요한 정보만 제한적으로 제공
2) 인증/인가 통제 가능 ex) 카카오톡 친구 목록
- 아무나 친구 목록을 볼 수 없음
- 로그인한 사용자만 자신의 친구 목록을 볼 수 있음
이렇게 API는 마치 안전하고 편리한 "만능 리모컨" 같은 역할을 합니다. 직접 TV 회로를 만지지 않고도 리모컨으로 쉽게 TV를 제어할 수 있는 것처럼, API를 통해 안전하고 효율적으로 다양한 서비스를 이용할 수 있습니다.
실생활 비유 🏪
전체 프로세스 쉽게 이해하기 🏪
레스토랑을 예로 들어보겠습니다:
손님 → 메뉴판 확인 → 웨이터에게 주문 → 웨이터가 주방에 전달 → 주방에서 음식 준비 → 웨이터가 음식 전달 → 손님
* 비교대상
손님(클라이언트) = 프로그램 사용자
메뉴판(API) = 사용 가능한 서비스 목록
웨이터(API) = 주문을 주방에 전달하고 음식을 가져오는 중개자
주방(서버) = 실제 서비스를 처리하는 곳
이것을 실제 프로그래밍으로 보면:
클라이언트 → API 문서 확인 → API 호출 → 서버에 요청 전달 → 서버에서 처리 → 응답 전달 → 클라이언트
이것을 '개발자입장'에서만 보면:
API 문서 확인 (메뉴판 보기) → API 연동 코드 작성 (주문 방법 익히기) → API 호출 테스트 (실제 주문해보기) → 서비스에 적용 (실제 서비스에 도입)
ex) 카카오지도 사용시,
카카오 개발자 사이트에서 API 키 발급 → API 문서 보고 지도 표시 코드 작성 → 테스트 후 서비스에 적용
-
API 문서 확인 (메뉴판 보기)
- 카카오 개발자 사이트 접속
- API 사용법 학습
- API 키 발급받기
-
API 연동 코드 작성 (주문 방법 익히기)
- API 호출 코드 작성
- 인증 정보 설정
- 에러 처리 로직 구현
-
API 호출 테스트 (실제 주문해보기)
- Postman 등으로 테스트
- 응답 확인
- 에러 상황 테스트
-
서비스에 적용 (실제 서비스에 도입)
- 프로그램에 API 연동
- 모니터링
- 유지보수
이것을 '클라이언트(손님)입장'에서만 보면:
서비스 이용(메뉴고르기) → API 자동 호출 (주문이 주방으로) → 결과 확인 (음식 받기)
ex) 카카오지도 사용시,
웹사이트에서 '지도 보기' 클릭 → 자동으로 지도 표시 (API 호출은 백그라운드) → 지도 확인 및 사용
-
서비스 이용 (메뉴 고르기)
- 지도 보기 버튼 클릭
- 결제하기 버튼 클릭
- 로그인 버튼 클릭
-
API 자동 호출 (주문이 주방으로)
- 버튼 클릭시 자동으로 API 호출
- 백그라운드에서 처리
- 사용자는 API 존재를 모름
-
결과 확인 (음식 받기)
- 지도가 화면에 표시됨
- 결제가 완료됨
- 로그인이 처리됨
이처럼 개발자는 API의 모든 과정을 알고 구현해야 하지만, 일반 사용자는 API의 존재를 모른 채 서비스를 이용하게 됩니다!
API가 메뉴판과 웨이터로 나뉘는 이유 📋
1) 메뉴판으로서의 API (API 문서)
- 어떤 서비스를 요청할 수 있는지 보여줌
- 요청 방법과 필요한 정보를 설명
- API문서플랫폼 : Swagger UI, Postman Documentation, GitBook, ReadTheDocs
- 예시1(쉬운예)
plaintext
주문 가능한 메뉴: 피자
필요한 정보: 크기, 토핑, 수량
가격: 20,000원- 예시2(대표적인 API문서 확인하기-Swagger/OpenAPI)
/api/users:
get:
summary: 사용자 목록 조회
parameters:
- name: page
in: query
description: 페이지 번호
required: true
responses:
200:
description: 성공
content:
application/json:
example:
users: [
{ "id": 1, "name": "김철수" },
{ "id": 2, "name": "이영희" }
]2) 웨이터로서의 API (실제 API)
- 실제로 요청을 전달하고 응답을 가져오는 역할
- 클라이언트와 서버 사이의 중개자
- 예시(쉬운예)
POST /order/pizza
{
"size": "large",
"topping": "페퍼로니",
"quantity": 1
}- 예시2(API호출방법-JavaScript로 호출)
// GET 요청 예시
fetch('https://api.example.com/users?page=1')
.then(response => response.json())
.then(data => console.log(data));
// POST 요청 예시
fetch('https://api.example.com/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: '김철수',
email: 'kim@example.com'
})
});- 예시(API호출방법-Postman으로 호출)
GET https://api.example.com/users?page=1
Authorization: Bearer your-token-here- 예시(API호출방법-Curl로 호출)
# GET 요청
curl https://api.example.com/users?page=1
# POST 요청
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "김철수", "email": "kim@example.com"}'이렇게 나누는 이유는:
- 사용자(클라이언트)가 먼저 무엇을 요청할 수 있는지 알아야 함 (메뉴판)
- 실제 요청을 적절한 형식으로 전달해야 함 (웨이터)
이해하기 쉽게 실제 코드로 보면:
// 메뉴판 역할 (API 문서)
/*
GET /users
설명: 사용자 목록을 가져옵니다
필요한 파라미터: page, limit
*/
// 웨이터 역할 (실제 API 호출)
fetch('https://api.example.com/users?page=1&limit=10')
.then(response => response.json())
.then(data => console.log(data));API 종류 📑
-
REST API(REpresentational State Transfer)
ex) 카카오&naver 지도 API, Twitter API- 가장 일반적으로 널리 사용되는 API방식
- HTTP 프로토콜을 최대한 활용하는 아키텍처
- HTTP 메서드 사용 (GET, POST, PUT, DELETE)
GET /users # 사용자 목록 조회 POST /users # 새 사용자 생성 PUT /users/123 # 사용자 정보 수정 DELETE /users/123 # 사용자 삭제 ``` -
SOAP API(Simple Object Access Protocol)
ex) 금융권 시스템, 기업 ERP 시스템, 레거시 웹서비스- 주로 기업용 솔루션에서 주로 사용
- XML 기반의 메시지 교환 프로토콜
- XML 형식 사용
<soap:Envelope> <soap:Body> <GetUser> <UserId>123</UserId> </GetUser> </soap:Body> </soap:Envelope> -
GraphQL
ex) GitHub API, Instagram API, Shopify API- 필요한 데이터만 선택적으로 가져올 수 있음
- 페이스북에서 개발한 쿼리 언어
- 하나의 엔드포인트로 다양한 요청 처리
query {
user(id: 123) {
name
email
posts {
title
}
}
}API별 장단점
REST API(일반적인 웹 서비스)
(장) HTTP 표준 준수 || (단) 오버페칭/언더페칭 문제
(장) 이해하기 쉬움
SOAP API(보안이 중요한 기업용 서비스)
(장) 높은 안정성 || (단) 무거움, 복잡함
(장) 엄격한 표준
GraphQL(복잡한 데이터 요청이 필요한 서비스)
(장) 효율적인 데이터 로딩 || (단) 학습 곡선이 높음
(장) 유연한 데이터 요청
API 호출 시 주의사항
1. 인증 정보 (Authorization) 🔑
API를 호출할 때는 대부분 '신분증'이 필요합니다.
실생활 예시:
- 은행 창구에서 통장을 만들 때 신분증이 필요한 것처럼
- API도 "너 누구야?"라고 확인하는 과정이 필요해요
인증 방법:
// 1. Bearer Token 방식
fetch('https://api.example.com/users', {
headers: {
'Authorization': 'Bearer abc123xyz789' // 신분증 역할
}
})
// 2. API Key 방식
fetch('https://api.example.com/users?api_key=abc123xyz789')2. 에러 처리 ⚠️
API 호출이 실패할 수 있는 여러 상황에 대비해야 합니다.
실생활 예시- 식당에서 주문할 때:
- "죄송합니다, 재료가 떨어졌어요" (404 에러)
- "지금은 주문이 너무 많아요" (429 에러)
- "신분증을 보여주세요" (401 에러)
자세한 에러 처리 예시:
fetch('https://api.example.com/users')
.then(response => {
if (response.status === 401) {
throw new Error('인증 실패! 로그인이 필요합니다');
}
if (response.status === 404) {
throw new Error('찾는 정보가 없습니다');
}
if (response.status === 429) {
throw new Error('너무 많은 요청을 보냈습니다. 잠시 후 다시 시도하세요');
}
if (!response.ok) {
throw new Error('알 수 없는 에러가 발생했습니다');
}
return response.json();
})
.then(data => {
console.log('성공:', data);
})
.catch(error => {
console.error('실패:', error.message);
// 에러 발생 시 사용자에게 알림
alert(error.message);
});3. 주요 에러 코드 📝
401: 인증 실패 (신분증이 잘못됨)
403: 권한 없음 (신분증은 맞지만 권한이 없음)
404: 찾을 수 없음 (요청한 정보가 없음)
429: 너무 많은 요청 (잠시 후 다시 시도)
500: 서버 에러 (서버에 문제가 있음)이렇게 API를 사용할 때는:
1. 올바른 신분증(인증 정보) 제시
2. 발생할 수 있는 다양한 상황에 대한 대비(에러 처리)
가 매우 중요합니다!
실제 사용 예시 💻
# 날씨 정보 요청
GET https://api.weather.com/seoul
# 응답
{
"city": "서울",
"temperature": 23,
"weather": "맑음"
}API는 현대 소프트웨어 개발에서 매우 중요한 역할을 하며, 다양한 서비스들이 서로 연동되어 동작하는 것을 가능하게 합니다.
