API vs SDK 완벽 가이드: 개발자가 꼭 알아야 할 핵심 차이

삶이라는 여행 일기 2025. 12. 3. 10:21

소프트웨어 개발을 시작하면 가장 먼저 마주치는 용어가 API와 SDK입니다. 두 용어는 비슷해 보이지만 역할과 범위가 완전히 다릅니다. 이 글에서는 API와 SDK의 차이를 명확하게 이해할 수 있도록 쉽게 설명해드리겠습니다.

1. 핵심 요약: 한 문장으로 이해하기

API = 규칙서 (어떻게 요청하는가)
SDK = 공구세트 (어떻게 만드는가)

더 쉽게:

API: "이렇게 물어보면 이렇게 대답해줄게"
SDK: "이 도구들로 네가 직접 만들어봐"

2. API (Application Programming Interface)란?

2.1 기본 정의

API는 프로그램 간 소통 규칙입니다. 한 프로그램이 다른 프로그램의 기능을 사용할 수 있도록 정해진 약속입니다.

2.2 쉬운 비유

비유 1: 식당 메뉴판

고객(프로그램A) → 메뉴판(API) → 주방(프로그램B)

"불고기 정식 주세요" (요청)
    ↓
메뉴판에 정해진 규칙대로 주문
    ↓
"네, 여기 있습니다" (응답)

핵심: 주방이 어떻게 요리하는지 몰라도 됨. 메뉴판(API)만 보면 됨.

비유 2: 자판기

[자판기 = API]

버튼 1: 콜라 (1000원)
버튼 2: 사이다 (1000원)
버튼 3: 커피 (800원)

→ 정해진 버튼을 누르면 정해진 음료가 나옴
→ 내부 작동 원리는 몰라도 됨

2.3 API의 구성

구성 요소설명예시

엔드포인트	요청을 보내는 주소	https://api.example.com/users
메서드	요청 방식	GET, POST, PUT, DELETE
파라미터	요청 시 전달하는 정보	user_id=123
응답 형식	받는 데이터 형태	JSON, XML
인증	접근 권한 확인	API Key, OAuth

2.4 실제 API 예시

예시 1: 날씨 API

요청:
GET https://api.weather.com/current?city=Seoul

응답:
{
  "city": "Seoul",
  "temperature": 15,
  "condition": "Sunny"
}

의미: "서울 날씨 알려줘" → "15도, 맑음"

예시 2: 카카오 로그인 API

요청:
POST https://kauth.kakao.com/oauth/token
{
  "grant_type": "authorization_code",
  "client_id": "YOUR_APP_KEY",
  "code": "AUTHORIZATION_CODE"
}

응답:
{
  "access_token": "xxxxxx",
  "token_type": "bearer",
  "expires_in": 3600
}

의미: "이 사용자 인증해줘" → "인증 토큰 여기 있어"

2.5 API의 장점

간편함: 복잡한 기능을 간단히 호출

재사용성: 여러 프로그램에서 같은 기능 사용

추상화: 내부 구현 몰라도 됨

업데이트 용이: 내부 변경해도 인터페이스만 유지하면 OK

3. SDK (Software Development Kit)란?

3.1 기본 정의

SDK는 소프트웨어 개발 도구 모음입니다. 특정 플랫폼이나 서비스를 위한 프로그램을 쉽게 만들 수 있도록 필요한 모든 도구를 제공합니다.

3.2 쉬운 비유

비유 1: 주방 전체 세트

[SDK = 주방 풀세트]

포함 내용:
- 칼, 도마, 냄비 (라이브러리)
- 레시피북 (문서)
- 요리 예제 (샘플 코드)
- 조미료 세트 (유틸리티)
- 가스레인지 (개발 도구)

→ 요리(프로그램)를 직접 만들 수 있음

비유 2: 레고 세트

[SDK = 테마별 레고 세트]

레고 우주선 세트:
- 블록들 (라이브러리)
- 조립 설명서 (문서)
- 완성된 예제 사진 (샘플)
- 특수 부품 (전용 도구)

→ 우주선을 직접 만들 수 있음

3.3 SDK의 구성

구성 요소설명예시

API	핵심 기능 호출 인터페이스	함수, 메서드
라이브러리	미리 작성된 코드 모음	.dll, .so, .jar 파일
문서	사용 설명서	API 레퍼런스, 가이드
샘플 코드	실제 사용 예제	예제 프로젝트
개발 도구	보조 프로그램	디버거, 에뮬레이터
드라이버	하드웨어 연결	카메라, 센서 드라이버

3.4 실제 SDK 예시

예시 1: Android SDK

[Android SDK 구성]

📦 SDK 패키지:
├─ 📁 platform-tools
│   ├─ adb.exe (디버깅 도구)
│   └─ fastboot.exe
├─ 📁 platforms
│   └─ android-33 (API 라이브러리)
├─ 📁 build-tools
│   └─ 33.0.0 (빌드 도구)
├─ 📁 sources
│   └─ android-33 (소스 코드)
├─ 📁 samples
│   └─ 예제 앱 프로젝트
└─ 📁 docs
    └─ API 문서

목적: 안드로이드 앱을 만들 수 있음

예시 2: 열화상 카메라 SDK (HIKMICRO)

[HIKMICRO SDK 구성]

📦 Camera SDK:
├─ 📁 lib
│   ├─ HZSDK.dll (핵심 라이브러리)
│   └─ ImageProcess.dll
├─ 📁 include
│   └─ HZSDK.h (헤더 파일)
├─ 📁 drivers
│   └─ USB_Driver.exe
├─ 📁 examples
│   ├─ CSharp_Example
│   ├─ Python_Example
│   └─ Cpp_Example
└─ 📁 docs
    ├─ API_Reference.pdf
    └─ User_Guide.pdf

목적: 열화상 카메라 제어 프로그램을 만들 수 있음

3.5 SDK의 장점

완전한 도구: 개발에 필요한 모든 것 포함

빠른 개발: 예제와 문서로 시간 절약

최적화: 해당 플랫폼에 최적화된 코드

지원: 공식 지원과 커뮤니티

4. API vs SDK: 핵심 차이점

4.1 비교표

항목APISDK

정의	프로그램 간 소통 규칙	개발 도구 모음
역할	기능 호출 방법 제공	프로그램 개발 지원
범위	좁음 (인터페이스만)	넓음 (도구 전체)
구성	엔드포인트, 메서드, 파라미터	API + 라이브러리 + 문서 + 도구
목적	기능 사용	프로그램 개발
사용자	프로그램	개발자
형태	문서, URL, 함수 명세	파일, 패키지, 도구
포함 관계	SDK에 포함될 수 있음	API를 포함함

4.2 포함 관계

┌─────────────────────────────┐
│         SDK                 │
│  ┌───────────────────────┐  │
│  │   API                 │  │
│  │   (핵심 인터페이스)    │  │
│  └───────────────────────┘  │
│                             │
│  + 라이브러리               │
│  + 문서                     │
│  + 예제 코드                │
│  + 개발 도구                │
│  + 드라이버                 │
└─────────────────────────────┘

핵심: SDK는 API를 포함하는 상위 개념

4.3 실제 사례 비교

사례 1: 구글 맵

Google Maps API:

javascript

// API 호출 (웹에서 URL로 직접 요청)
https://maps.googleapis.com/maps/api/geocode/json?address=Seoul

// 응답
{
  "results": [{
    "geometry": {
      "location": {"lat": 37.5665, "lng": 126.9780}
    }
  }]
}

→ 위치 정보만 받아옴

Google Maps SDK (Android):

java

// SDK 사용 (라이브러리 import 후 코드 작성)
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.MapView;

MapView mapView = findViewById(R.id.mapView);
GoogleMap map = mapView.getMap();
map.addMarker(new MarkerOptions()
    .position(new LatLng(37.5665, 126.9780))
    .title("Seoul"));

→ 지도를 앱에 직접 표시 가능

사례 2: 산업용 카메라

카메라 API:

python

# HTTP API로 이미지 요청
import requests

response = requests.get("http://camera-ip/api/capture")
image_data = response.json()

→ 단순히 기능 호출

카메라 SDK:

python

# SDK 라이브러리 사용
from hikmicro_sdk import Camera, ImageProcess

camera = Camera()
camera.connect("192.168.1.100")
camera.set_resolution(640, 480)
camera.set_emissivity(0.95)

# 실시간 스트림
for frame in camera.stream():
    processed = ImageProcess.apply_palette(frame, "iron")
    temperature = ImageProcess.get_temperature(frame, x=320, y=240)
    print(f"Center temperature: {temperature}°C")

→ 카메라를 완전히 제어하는 프로그램 개발 가능

5. 언제 API를 사용하고, 언제 SDK를 사용하나?

5.1 API 사용이 적합한 경우

Case 1: 간단한 기능 호출

상황: 날씨 정보만 가져오면 됨
해결: OpenWeatherMap API 호출
코드: 10줄

장점: 빠르고 간단

Case 2: 웹 서비스 통합

상황: 웹사이트에 결제 기능 추가
해결: Stripe Payment API 사용
방식: JavaScript로 API 호출

장점: 별도 설치 불필요, 웹에서 바로 사용

Case 3: 서버-서버 통신

상황: 서버에서 다른 서버 데이터 가져오기
해결: REST API 호출
예시: 
  - 주문 서버 → 재고 서버 API
  - 결제 서버 → 은행 API

장점: 표준화된 HTTP 통신

5.2 SDK 사용이 적합한 경우

Case 1: 플랫폼 전용 앱 개발

상황: iOS 앱 개발
필요: iOS SDK
이유: 
  - 앱 라이프사이클 관리
  - UI 컴포넌트
  - 디바이스 기능 접근
  - 최적화된 성능

필수: SDK 없이는 앱 개발 불가

Case 2: 하드웨어 제어

상황: 열화상 카메라 제어 소프트웨어 개발
필요: 카메라 제조사 SDK
이유:
  - 드라이버 필요
  - 실시간 스트리밍
  - 이미지 처리 라이브러리
  - 하드웨어 최적화

필수: API만으로는 부족

Case 3: 복잡한 기능 구현

상황: 게임 개발
필요: Unity SDK 또는 Unreal Engine SDK
이유:
  - 물리 엔진
  - 렌더링 시스템
  - 애니메이션 도구
  - 에디터

필수: 수천 개의 기능을 직접 만들 수 없음

6. 실무 사례 연구

6.1 사례 1: 날씨 앱 개발

요구사항

현재 위치의 날씨 표시
일주일 예보
iOS/Android 앱

해결 방법

1단계: 날씨 데이터 → API 사용

OpenWeatherMap API 호출
- 간단한 HTTP 요청
- JSON 데이터 받기

2단계: 앱 개발 → SDK 사용

iOS: iOS SDK + Swift
Android: Android SDK + Kotlin

→ 앱 UI, 위치 서비스, 알림 등

결론: API와 SDK 둘 다 필요

6.2 사례 2: 공장 설비 모니터링 시스템

요구사항

열화상 카메라로 온도 감시
이상 온도 시 알람
데이터 저장 및 분석

해결 방법

1단계: 카메라 제어 → SDK 사용

HIKMICRO Camera SDK
- 실시간 영상 스트리밍
- 온도 데이터 추출
- 카메라 설정 제어

2단계: 서버 통신 → API 사용

자체 REST API 개발
- 온도 데이터 전송
- 알람 이력 조회
- 설정 변경

3단계: 웹 대시보드 → API 사용

서버 API 호출
- 실시간 데이터 표시
- 차트 생성
- 알람 관리

결론: SDK로 카메라 제어 프로그램 개발 → API로 시스템 통합

6.3 사례 3: 소셜 로그인 구현

요구사항

카카오/네이버/구글 로그인
웹사이트용

해결 방법

선택 1: API 사용 (웹)

javascript

// 카카오 로그인 API
Kakao.Auth.login({
  success: function(authObj) {
    console.log(authObj.access_token);
  }
});

→ 간단, 빠름, 웹에 최적

선택 2: SDK 사용 (앱)

java

// 카카오 로그인 SDK (Android)
UserApiClient.instance.loginWithKakaoTalk(context) { token, error ->
    if (error != null) {
        Log.e(TAG, "로그인 실패", error)
    } else {
        Log.i(TAG, "로그인 성공 ${token?.accessToken}")
    }
}

→ 앱 개발 시 필수

결론:

웹 → API로 충분
앱 → SDK 필요

7. API와 SDK의 발전 트렌드

7.1 REST API → GraphQL API

전통적 REST API:

GET /users/123
GET /users/123/posts
GET /users/123/posts/1/comments

→ 여러 번 호출 필요

현대적 GraphQL API:

graphql

query {
  user(id: 123) {
    name
    posts {
      title
      comments {
        text
      }
    }
  }
}

→ 한 번에 필요한 데이터만

7.2 SDK의 경량화

과거 SDK:

크기: 수백 MB~GB
설치: 복잡한 설치 과정
의존성: 많은 추가 패키지

현대 SDK:

크기: 수십 MB 이하
설치: 간단한 패키지 관리 (npm, pip, maven)
의존성: 자동 해결

bash

# 과거
1. SDK 다운로드 (500MB)
2. 압축 해제
3. 환경변수 설정
4. 의존성 수동 설치

# 현재
pip install hikmicro-sdk

7.3 Cloud SDK의 등장

특징:

서버에서 실행
로컬 설치 불필요
자동 업데이트

예시:

AWS Lambda: 코드만 업로드, SDK는 서버에 내장
Google Colab: 브라우저에서 Python SDK 사용

8. 자주 묻는 질문 (FAQ)

Q1. API만으로 앱을 만들 수 있나요?

답변: 웹 앱은 가능하지만, 네이티브 앱은 SDK가 필수입니다.

웹 앱: HTML + JavaScript + API 호출 → 가능
iOS/Android 앱: SDK 없이는 불가능

Q2. SDK 없이 하드웨어를 제어할 수 있나요?

답변: 이론적으로 가능하지만 매우 어렵습니다.

SDK 사용:
camera.capture()  // 간단!

SDK 없이:
- USB 통신 프로토콜 분석
- 하드웨어 명령어 연구
- 드라이버 직접 작성
- 수개월 소요

결론: 실용적으로는 SDK 필수

Q3. 무료 API와 유료 SDK의 차이는?

답변: 용도와 지원 수준이 다릅니다.

구분무료 API유료 SDK

기능	기본 기능	전체 기능 + 고급 기능
제한	호출 횟수 제한	제한 없음
지원	커뮤니티	공식 기술 지원
문서	기본 문서	상세 문서 + 교육
업데이트	느림	빠름

Q4. API 키와 SDK 라이선스는 다른가요?

답변: 네, 목적이 다릅니다.

API 키:

목적: API 호출 인증
형태: 문자열 (예: AIzaSyD...)
관리: 웹 콘솔에서 발급
사용: 코드에 포함

SDK 라이선스:

목적: SDK 사용 권한
형태: 파일 또는 등록 코드
관리: 구매/계약 후 발급
사용: 개발 환경에 설치

Q5. SDK를 사용하면 API를 직접 호출할 수 없나요?

답변: 아니요, SDK를 사용하면서도 API를 직접 호출할 수 있습니다.

python

# SDK 함수 사용
camera = SDK.Camera()
image = camera.capture()

# 동시에 API 직접 호출도 가능
import requests
response = requests.get("http://camera/api/status")

SDK는 편의성을 제공할 뿐, API 호출을 막지 않습니다.

9. 개발자를 위한 실전 팁

Tip 1: API 먼저, SDK는 필요할 때

개발 순서:
1. API로 프로토타입 제작 (빠름)
2. 기능 검증
3. 필요하면 SDK로 전환 (고급 기능)

장점: 시간 절약, 리스크 감소

Tip 2: SDK 선택 시 체크리스트

문서가 충분한가?
예제 코드가 있는가?
커뮤니티가 활성화되어 있는가?
업데이트가 주기적인가?
라이선스가 적합한가?
지원 플랫폼이 맞는가?

Tip 3: API 버전 관리

좋은 예:
https://api.example.com/v2/users

나쁜 예:
https://api.example.com/users  (버전 없음)

버전이 있어야 이전 버전 호환성 유지

Tip 4: SDK 업데이트 주의

python

# 특정 버전 고정 (권장)
pip install hikmicro-sdk==2.1.0

# 최신 버전 (주의: 호환성 문제 가능)
pip install hikmicro-sdk

중요한 프로젝트는 버전 고정

10. 핵심 요약

API (Application Programming Interface):

정의: 프로그램 간 소통 규칙
비유: 식당 메뉴판, 자판기 버튼
목적: 기능을 호출하는 방법 제공
구성: 엔드포인트, 메서드, 파라미터

SDK (Software Development Kit):

정의: 소프트웨어 개발 도구 모음
비유: 주방 풀세트, 레고 세트
목적: 프로그램을 만들 수 있게 지원
구성: API + 라이브러리 + 문서 + 도구

포함 관계

SDK ⊃ API

SDK = API + α (추가 도구들)

선택 가이드

상황선택

간단한 데이터 조회	API
웹 서비스 통합	API
앱 개발	SDK
하드웨어 제어	SDK
복잡한 기능 구현	SDK

최종 조언

API부터 시작하세요:

API로 빠르게 프로토타입
기능 검증
필요 시 SDK로 확장

SDK는 신중하게 선택하세요:

문서 품질 확인
커뮤니티 활성도 확인
라이선스 검토
장기 지원 여부 확인

API와 SDK는 소프트웨어 개발의 양대 산맥입니다. 각각의 특성을 이해하고 적절히 활용하면, 더 빠르고 효율적인 개발이 가능합니다.

참고 자료:

RESTful API Design Best Practices
OAuth 2.0 Authorization Framework
Android SDK Developer Guide
iOS SDK Documentation