API란 무엇인가? 개념부터 실전 활용까지 “깊이 있게” 정리
요약
- API(Application Programming Interface)는 “프로그램이 다른 프로그램의 기능/데이터를 규칙에 맞게 요청하고 받는 방법”입니다.
- 초보가 API를 이해할 때 핵심은 용어가 아니라 요청(Request) → 처리(서버) → 응답(Response)의 왕복 흐름을 몸에 익히는 것입니다.
- 실무에서 API는 단순 호출을 넘어 인증, 권한, 에러 규격, 버전관리, 속도 제한, 페이징, 재시도 같은 운영 요소와 함께 설계됩니다.
- 이 글은 “API가 뭔가요?”에서 끝나지 않고, 왜 이런 규칙이 필요하고, 어떤 실수를 막기 위해 존재하는지까지 설명합니다.
목차
- 1. API의 기본 개념(한 문장 정의 + 감 잡는 비유)
- 2. 왜 API가 필요한가: 시스템이 커질수록 API가 “계약서”가 되는 이유
- 3. API를 읽는 기본 단어장: Endpoint/Method/Header/Body/Status
- 4. HTTP API의 동작 원리: 요청/응답이 실제로 오가는 방식
- 5. API 스타일: REST vs GraphQL vs gRPC(언제 무엇을 쓰나)
- 6. 인증과 권한: API Key, Bearer Token, OAuth2의 차이
- 7. 좋은 API 설계 원칙: 일관성, 버전, 에러 규격, 페이징
- 8. 실습: API 호출해 보기(curl/Fetch) + 흔한 실수 체크
- 실행 단계: 초보가 API를 “내 것”으로 만드는 학습 루트
- 블로그 최적화 정보
핵심 포인트
- API는 “기능을 쓰는 방법”이자 “데이터를 주고받는 규칙”이며, 결국 서로 다른 팀/서비스가 충돌 없이 협업하기 위한 계약입니다.
- API를 잘 쓰려면 요청을 구성하는 요소(메서드/URL/헤더/바디)와 응답을 해석하는 요소(상태코드/바디/에러 규격)를 분리해 이해해야 합니다.
- 실무 난이도를 올리는 것은 “호출”이 아니라 인증, 예외(에러), 제한(레이트 리밋), 변경(버전업) 같은 운영 문제입니다.
상세 설명
1) API의 기본 개념: 한 문장 정의 + 감 잡는 비유
API는 “어떤 기능을 어떻게 요청하면, 어떤 형태로 결과를 돌려주는지”를 정해둔 인터페이스입니다. 사람끼리 대화할 때도 규칙이 있듯이(언어/문법/예의), 프로그램끼리 대화할 때도 규칙이 필요합니다. 그 규칙이 API입니다.
초보에게 가장 직관적인 비유는 “식당”입니다.
- 당신(클라이언트)은 메뉴판을 보고 주문합니다.
- 주문서(요청)에는 무엇을 원하는지, 옵션은 무엇인지, 결제는 했는지 같은 정보가 담깁니다.
- 주방(서버)은 주문서를 규칙대로 해석해서 음식을 만듭니다.
- 음식(응답)이 나오고, 잘못된 주문이면 “품절/재료 없음/주문 오류” 같은 안내가 나옵니다(에러 응답).
중요한 점은 “주방 내부가 어떻게 돌아가는지”를 몰라도 메뉴판(=API 문서)대로 주문하면 결과를 받을 수 있다는 것입니다. API는 이렇게 시스템 내부를 감추고, 외부에서 쓸 수 있는 통로만 안전하게 열어줍니다.
2) 왜 API가 필요한가: 시스템이 커질수록 API가 “계약서”가 되는 이유
개발을 시작할 때는 하나의 앱(프론트)과 하나의 서버(백엔드) 정도로 단순하게 보이지만, 서비스가 커지면 기능과 팀이 늘어납니다. 결제, 배송, 회원, 알림, 추천, 재고 같은 도메인이 분리되면, 서로가 서로의 데이터와 기능을 직접 만지기 어렵습니다.
- 팀 A가 팀 B의 DB를 직접 건드리기 시작하면, 스키마 변경이 즉시 장애로 이어질 수 있습니다.
- 서로 다른 언어/프레임워크/배포 주기를 가진 서비스들이 공존하면, 내부 구현을 맞추는 것보다 “약속(계약)”을 맞추는 게 중요해집니다.
- 이때 API는 “우리가 이렇게 요청하면, 너희는 이렇게 응답해줘”라는 합의문이 됩니다.
즉 API는 단순한 기술 용어가 아니라, 변경을 관리하고 협업을 가능하게 하는 시스템의 경계선입니다.
3) API를 읽는 기본 단어장: Endpoint/Method/Header/Body/Status
API 문서를 처음 보면 낯선 용어가 많습니다. 하지만 대부분은 “요청을 구성하는 부품”입니다. 아래 표를 먼저 익히면, API 문서를 읽는 속도가 급격히 빨라집니다.
| 용어 | 뜻(초보용) | 한 문장 예시 | 실무에서 중요한 이유 |
|---|---|---|---|
| Endpoint | API가 제공하는 “주소(기능의 입구)” | /v1/users, /v1/orders | 주소 설계가 곧 사용성/일관성입니다. |
| HTTP Method | 무엇을 할지(조회/생성/수정/삭제) | GET, POST, PUT, PATCH, DELETE | 동작 의미를 표준화해 실수를 줄입니다. |
| Header | 요청/응답의 “메타 정보(봉투)” | Authorization, Content-Type | 인증/형식/캐시/추적이 헤더에서 이뤄집니다. |
| Body | 보내는 실제 데이터(본문) | JSON으로 사용자 정보 전송 | 스키마(필드 정의)가 깨지면 연동이 즉시 실패합니다. |
| Status Code | 결과가 성공/실패인지 숫자로 표현 | 200, 201, 400, 401, 404, 500 | 에러 처리와 재시도 전략이 여기서 갈립니다. |
4) HTTP API의 동작 원리: 요청/응답이 실제로 오가는 방식
웹에서 흔히 말하는 API는 대부분 HTTP 위에서 동작합니다. 즉 브라우저가 페이지를 요청하듯, 프로그램도 URL로 요청을 보내고 응답을 받습니다. 다만 “HTML 페이지”가 아니라, 보통 JSON 같은 데이터 형식을 주고받습니다.
코드 예시: 가장 기본적인 API 호출(curl)
# 1) 목록 조회: GET + Query Parameter
curl -X GET "https://api.example.com/v1/users?limit=10" \
-H "Accept: application/json"
# 2) 생성: POST + JSON Body
curl -X POST "[https://api.example.com/v1/users](https://api.example.com/v1/users)"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '{"name":"Kim","email":"[kim@example.com](mailto:kim@example.com)"}'
# 3) 인증이 필요한 경우(예: Bearer Token)
curl -X GET "[https://api.example.com/v1/me](https://api.example.com/v1/me)"
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Accept: application/json"위에서 초보가 꼭 체크해야 할 포인트는 3가지입니다. (1) URL(어디로), (2) Method(무엇을), (3) Header/Body(어떤 조건/데이터로). 이 3가지만 분리해서 보면 API 문서가 훨씬 단순하게 보입니다.
HTTP 메서드 감각 잡기: “동사”를 통일하면 실수가 줄어듭니다
| Method | 의미(기본) | 멱등성(Idempotent) | 예시 Endpoint | 현업 팁 |
|---|---|---|---|---|
| GET | 조회 | O | GET /v1/orders/123 | 조회는 바디 없이 쿼리/경로 파라미터로 표현하는 경우가 많습니다. |
| POST | 생성/요청(비정형 작업) | X | POST /v1/orders | 결제/전송/예약처럼 “한 번만 실행되어야 하는 작업”에 자주 쓰입니다. |
| PUT | 전체 교체 | O | PUT /v1/users/10 | 전체 필드를 보내는 관례가 많아 스키마 변경에 민감할 수 있습니다. |
| PATCH | 부분 수정 | 보통 O(설계에 따라) | PATCH /v1/users/10 | 변경 필드만 보내기 때문에 UI 변경에 유리합니다. |
| DELETE | 삭제 | O | DELETE /v1/orders/123 | 실무에서는 실제 삭제 대신 “소프트 삭제”로 상태만 바꾸는 경우도 많습니다. |
5) API 스타일: REST vs GraphQL vs gRPC(언제 무엇을 쓰나)
API는 모두 같은 모양이 아닙니다. 대표적인 스타일을 비교해두면, “왜 이런 문서 구조인가”가 이해됩니다.
| 스타일 | 핵심 특징 | 장점 | 단점/주의 | 추천 상황 |
|---|---|---|---|---|
| REST | 리소스 중심(URL) + HTTP 메서드 | 표준적, 캐시/로그/도구 생태계 풍부 | 화면별 필요한 데이터가 달라지면 엔드포인트가 늘 수 있음 | 대부분의 웹/모바일 서비스, 공용 API |
| GraphQL | 쿼리로 필요한 필드를 요청 | 필요한 데이터만 받기 쉬움, 프론트 주도 개발에 유리 | 캐시/권한/복잡한 쿼리 제한 설계가 어렵고 운영 난이도 상승 가능 | UI 조합이 잦고 요청 데이터 형태가 자주 바뀌는 서비스 |
| gRPC | 바이너리 프로토콜 + 스키마(Proto) | 성능/타입 안정성/내부 마이크로서비스 통신에 강점 | 브라우저 직접 호출 난이도, 운영/관찰성 도구가 REST보다 낯설 수 있음 | 서버 간 통신, 대규모 내부 서비스 |
6) 인증과 권한: API Key, Bearer Token, OAuth2의 차이
초보가 API에서 가장 먼저 막히는 지점은 “왜 401/403이 나오지?”입니다. 대부분 인증/권한 문제입니다. 간단히 구분하면 아래처럼 이해하시면 됩니다.
- 인증(Authentication): “너 누구야?”를 확인하는 절차
- 권한(Authorization): “너 이 기능 써도 돼?”를 확인하는 절차
| 방식 | 보통 어디에 넣나 | 특징 | 주의점 | 자주 쓰는 곳 |
|---|---|---|---|---|
| API Key | Header 또는 Query | 간단하지만 유출 시 위험 | 서버에서만 사용 권장(프론트 노출 주의) | 내부 도구, 제한된 파트너 연동 |
| Bearer Token(JWT 등) | Authorization: Bearer ... | 세션 대체, 모바일/SPA에서 흔함 | 만료/갱신/저장 위치(보안) 설계 필요 | 웹/앱 로그인 이후 API 호출 |
| OAuth2 | 토큰 발급 후 Bearer로 사용 | 3자 인증(구글 로그인 등) 표준 | 플로우가 복잡하지만 보안/권한 위임에 강함 | 소셜 로그인, 외부 플랫폼 연동 |
7) 좋은 API 설계 원칙: 일관성, 버전, 에러 규격, 페이징
API를 “깊이 있게” 이해하려면, 단순 호출법을 넘어서 운영 관점의 설계를 함께 봐야 합니다. 아래 항목은 실무에서 장애와 비용을 줄이는 데 직접적으로 영향을 줍니다.
- 일관된 규칙: 같은 의미는 같은 방식으로 표현(예: 날짜 형식, 필드 네이밍, 상태코드 사용)
- 버전관리: /v1, /v2 또는 헤더 기반 버전으로 “변경”을 통제
- 에러 규격: 에러도 스키마를 가져야 클라이언트가 안정적으로 처리 가능
- 페이징: limit/offset 또는 cursor 기반으로 대량 데이터 조회를 안전하게
- 레이트 리밋: 과도한 호출로 서비스가 무너지는 것을 방지
- 멱등성 키: 결제/주문 같은 “중복 실행이 위험한 작업”에서 중복 방지
예를 들어 “에러 규격”은 초보가 놓치기 쉽지만, 운영에서 매우 중요합니다. 단순히 400/500을 던지면 끝이 아니라, 클라이언트가 “무엇을 고쳐야 하는지”를 기계적으로 판단할 수 있어야 합니다.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "입력값이 올바르지 않습니다.",
"details": [
{ "field": "email", "reason": "INVALID_FORMAT" }
],
"traceId": "c2f1d0b9-8a2d-4f3d-9a0b-xxxx"
}
}이런 형태로 에러를 표준화하면, 화면에서는 message를 보여주고, 개발자는 details로 디버깅하며, 운영/로그에서는 traceId로 추적할 수 있습니다. API가 “계약서”라는 말이 여기서 체감됩니다.
8) 실습: Fetch로 API 호출해 보기(초보가 자주 틀리는 포인트 포함)
브라우저/프론트에서 API를 호출할 때는 fetch를 자주 사용합니다. 아래 예시는 JSON을 보내고 JSON을 받는 가장 흔한 형태입니다.
async function createUser() {
const res = await fetch("https://api.example.com/v1/users", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
},
body: JSON.stringify({ name: "Kim", email: "kim@example.com" })
});
// ✅ 초보가 자주 놓치는 부분: res.ok(2xx)가 아니면 에러 바디를 읽고 분기 처리해야 합니다.
const data = await res.json().catch(() => null);
if (!res.ok) {
console.log("요청 실패:", res.status, data);
throw new Error(data?.error?.message || "API 요청 실패");
}
return data;
}여기서 자주 발생하는 실수는 아래 4가지입니다.
- Content-Type 누락: JSON을 보냈는데 서버가 폼으로 해석하거나 바디를 비워서 받는 경우가 생깁니다.
- 상태코드 분기 누락: 400/401/500이어도 json()이 성공하면 “성공처럼” 보여 디버깅이 늦어집니다.
- CORS 오해: 브라우저에서만 발생하는 정책 이슈인데, API 자체 문제로 착각하는 경우가 많습니다.
- 재시도/타임아웃 미설계: 네트워크는 언제든 흔들립니다. 중요한 호출은 재시도/백오프 전략이 필요합니다.
실행 단계: 초보가 API를 “내 것”으로 만드는 학습 루트
- API 문서에서 엔드포인트 1개를 고르고, “URL/Method/필수 헤더/필수 바디”만 따로 적어보세요. 처음엔 전체를 이해하려고 하기보다, 요청의 뼈대만 잡는 게 빠릅니다.
- curl로 먼저 호출해 성공/실패를 확인합니다. 이 단계는 브라우저 환경(CORS 등) 영향을 줄여 “순수하게 API가 되는지”를 확인하는 데 유리합니다.
- 상태코드별로 대응을 분리해 보세요. 200/201(성공), 400(입력 오류), 401/403(인증/권한), 404(대상 없음), 429(제한), 500(서버 문제) 정도만 잡아도 운영 안정성이 크게 올라갑니다.
- 페이징이 있는 API라면 limit/offset 또는 cursor 방식이 무엇인지 확인하고, “다음 페이지를 어떻게 가져오는지”를 직접 구현해 보세요. 데이터량이 늘어나는 순간 여기서 막히는 경우가 매우 많습니다.
- 인증 방식(API Key/Bearer/OAuth2)을 분리해 이해하고, 토큰 만료/갱신 시나리오까지 상상해 보세요. 실무 난이도의 절반은 인증과 예외 처리에서 나옵니다.
- 마지막으로 “작은 API”를 직접 만들어보면 이해가 가장 깊어집니다. 예를 들어 메모 목록 조회/추가/삭제 정도를 만들고, 에러 규격과 버전(/v1)을 붙여보면 API의 ‘계약’ 감각이 확실히 잡힙니다.
추가로 생각해볼 점
- API는 기술이면서 동시에 “조직의 약속”입니다. 좋은 API는 호출이 쉬운 것뿐 아니라, 변경에 강하고, 장애에 덜 흔들리고, 문서화가 잘 되어 있는 것입니다.
- 처음에는 REST로 시작하는 편이 학습 효율이 좋습니다. HTTP 표준 도구(curl, 브라우저, 로그, 프록시)가 풍부해 관찰과 디버깅이 쉽기 때문입니다.
- API를 깊게 이해하고 싶다면 “성공 케이스”보다 실패 케이스(에러/재시도/제한/권한)를 더 많이 다뤄보는 것을 추천합니다. 실무는 실패를 처리하는 능력에서 차이가 납니다.
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
0 댓글