API란 무엇인가

19.1 Claude가 모르는 것

4.7절에서 말씀드린 한계를 다시 꺼냅니다.

실시간 인터넷 정보 — 오늘 환율, 지금 주가, 어제 올라온 블로그 글. 기본 상태로는 모릅니다.

3.3절의 원리 때문입니다. LLM은 미리 읽어둔 글로 답합니다. 오늘 일어난 일은 그 안에 없습니다.

그런데 우리가 하려는 업무에는 바깥 정보가 필요할 때가 많습니다.

• 네이버에서 이 키워드로 블로그 글이 몇 개 나오는지
• 우리 채널의 최근 영상 조회수가 얼마인지
• 이번 달 쇼핑 트렌드가 어떤지

이걸 가져오는 창구가 API 입니다.

---

19.2 API — 회사가 열어둔 창구

📖 API(Application Programming Interface, 응용 프로그램 인터페이스)

어떤 회사의 정보나 기능을 프로그램이 가져다 쓸 수 있게 열어둔 창구.

사람은 웹사이트로 들어가서 눈으로 봅니다. 프로그램은 API로 들어가서 데이터로 받습니다. 같은 정보를 사람용 문과 프로그램용 문으로 나눠 연 것입니다.

식당으로 비유하면

주방이 어떻게 돌아가는지 몰라도 주문할 수 있습니다. 이게 API의 핵심입니다. 네이버가 검색을 어떻게 하는지 몰라도, 정해진 방식으로 요청하면 결과를 줍니다.

세 가지 용어

주문 한 번에 세 단어가 나옵니다.

📖 엔드포인트(endpoint)

주문을 받는 창구의 주소. 웹 주소처럼 생겼습니다.

https://openapi.naver.com/v1/search/blog.json

“네이버 오픈API의, 검색 중에서, 블로그를, JSON 형식으로” 라는 뜻입니다. 창구마다 주소가 다릅니다. 책을 검색하려면 blog 자리가 book 이 됩니다.

📖 요청(request) / 응답(response)

요청 — 내가 보내는 주문. “이 검색어로, 10개만, 최신순으로” 응답 — 돌아오는 결과. 대개 JSON(14.5절) 형식입니다.

---

19.3 열쇠 — Client ID와 Secret

식당은 아무나 들어가지만, API는 누가 주문했는지 확인합니다.

이유는 두 가지입니다.

그래서 미리 신청해서 열쇠를 받습니다.

📖 Client ID / Client Secret

API를 쓸 때 “나는 누구다” 를 증명하는 한 쌍.

• Client ID — 내 아이디 (공개돼도 비교적 괜찮음)
• Client Secret — 내 비밀번호 (절대 공개하면 안 됨)

은행 계좌번호와 비밀번호 같은 관계입니다. 계좌번호는 알려줄 수 있지만 비밀번호는 안 되죠.

---

19.4 실습 — 네이버 검색 API 키 받기

가장 만만한 API로 해보겠습니다. 네이버 검색 API는 무료이고, 하루 2만 5천 번 까지 쓸 수 있습니다. 개인이 쓰기에는 사실상 무제한입니다.

① 애플리케이션 등록

1. 네이버 개발자센터(developers.naver.com)에 네이버 계정으로 로그인
2. 애플리케이션 등록
3. 애플리케이션 이름을 적습니다 (아무거나. “내 검색 도구” 같은 것)
4. 사용할 API에서 검색을 고릅니다
5. 등록하면 Client ID 와 Client Secret 이 나옵니다

[그림 19-1: 네이버 개발자센터 애플리케이션 등록 화면. ① 이름 입력 ② API 선택 ③ 등록 버튼]

② 확인해 보기

Claude에게 시켜봅니다. 키는 아직 붙여넣지 마세요. 19.5절을 읽고 하세요.

네이버 검색 API로 "제주 맛집" 을 블로그에서 검색해서
제목과 링크를 10개 가져오는 파이썬 코드를 만들어줘.

Client ID와 Secret은 코드에 직접 쓰지 말고,
.env 파일에서 읽어오게 해줘.

마지막 문장이 이 장에서 제일 중요합니다.

---

19.5 비밀키를 코드에 적으면 안 되는 이유

⚠️ 이 책에서 가장 조심하라고 말하는 사고입니다

코드 안에 이렇게 적으면 안 됩니다.

CLIENT_SECRET = "aB3xK9pQr2"      # ← 절대 이렇게 하지 마세요

왜냐하면 —

상황	무슨 일이 생기나
코드를 GitHub에 올림	전 세계에 공개됩니다
동료에게 파일을 보냄	그 사람이 내 키를 갖게 됩니다
블로그에 코드를 자랑	스크린샷에 찍혀 나갑니다
코드를 누가 복사해 감	내 한도를 남이 씁니다

실제로 GitHub에 올라온 API 키를 자동으로 찾아다니는 프로그램이 돌아다닙니다. 올린 지 몇 분 만에 발견됩니다.

해결 — 환경변수

📖 환경변수(environment variable)

코드 바깥에 따로 적어두고, 프로그램이 실행될 때 꺼내 쓰는 값.

보통 .env 라는 파일에 적습니다.

NAVER_CLIENT_ID=abcd1234
NAVER_CLIENT_SECRET=aB3xK9pQr2

코드에는 “.env 에서 꺼내 쓴다” 는 문장만 있습니다. 값은 없습니다.

이러면 코드를 남에게 줘도 안전합니다. .env 파일만 안 주면 되니까요.

한 가지 더 — .gitignore

.env 파일을 만들었어도, 실수로 같이 올라가는 것을 막아야 합니다.

.env

이 한 줄을 .gitignore 라는 파일에 적어두면, Git이 .env 를 아예 못 본 척 합니다. 1장에서 깐 Git이 여기서 일합니다.

Claude에게 시키면 됩니다.

.gitignore 파일을 만들어서 .env 를 제외하도록 해줘

💡 이 규칙은 CLAUDE.md 에 박아두세요

## 보안
- API 키·비밀번호를 코드에 직접 쓰지 않는다. 항상 .env 에서 읽는다.
- .env 는 .gitignore 에 반드시 포함한다.

7장에서 배운 대로, 두 번 말할 것 같으면 파일에 적습니다. 그리고 이건 두 번이 아니라 매번 지켜야 하는 규칙입니다.

---

19.6 API 문서 읽는 법

API를 쓰려면 그 회사가 만든 설명서를 봐야 합니다. 처음 보면 무섭게 생겼는데, 볼 곳은 네 군데뿐입니다.

②번 표를 읽는 법

문서에는 이런 표가 있습니다.

• 필수가 Y면 반드시 보내야 합니다. 안 보내면 오류입니다
• N이면 안 보내도 됩니다. 기본값이 적용됩니다
• 고를 수 있는 값이 정해져 있으면 그 안에서만 써야 합니다

그런데 사실은

💡 문서를 Claude에게 읽히세요

이게 이 책 독자에게 가장 현실적인 방법입니다.

https://developers.naver.com/docs/serviceapi/search/blog/blog.md
이 문서를 읽고, 내가 알아야 할 핵심만 정리해줘.
어떤 값을 꼭 보내야 하고, 뭐가 돌아오는지.

다만 돌아온 내용을 그대로 믿지는 마세요. 3.3절의 환각입니다. 실제로 한 번 호출해 보고, 나온 결과로 확인하는 게 맞습니다.

---

19.7 한도와 예의

⚠️ API에는 하루 한도가 있습니다

네이버 검색은 2만 5천 회로 넉넉하지만, 같은 네이버라도 창구마다 다릅니다.

창구	하루 한도
검색	25,000회
데이터랩(검색어 트렌드)	1,000회
카페 글쓰기	200회
카페 가입	50회

한도를 넘으면 그날은 더 못 씁니다.

그리고 프로그램은 사람보다 훨씬 빠르게 요청합니다. 반복문을 잘못 짜면 몇 초 만에 한도를 다 씁니다. 처음 돌릴 때는 개수를 작게 잡으세요.

---

19.8 🔁 혼자 해보기

1. 네이버 개발자센터에서 검색 API 키를 발급받으세요
2. .env 파일에 키를 넣고, .gitignore 에 .env 를 추가하세요
3. Claude에게 검색 코드를 만들게 해서 한 번 돌려보세요
4. 일부러 키를 틀리게 넣고 돌려보세요. 어떤 오류가 나오는지 보세요
5. CLAUDE.md 에 19.5절의 보안 규칙 두 줄을 추가하세요

4번이 중요합니다. 오류 메시지를 한 번 봐두면 나중에 실제로 났을 때 당황하지 않습니다.

---

19.9 정리

다음 장에서는 이 API를 써서 실제로 쓸 수 있는 물건을 하나 만듭니다. 크롬 브라우저에 붙는 확장 프로그램입니다.