API란 무엇인가

어디서 온 말이고, 어떻게 한 번의 요청으로 이어지나

위키백과에 따르면 API의 발상은 1940년대로 거슬러 올라갑니다. 모리스 윌크스와 데이비드 휠러가 EDSAC용으로 만든 모듈식 서브루틴 라이브러리와 사용 설명 목록이 최초의 공개된 API 명세로 소개됩니다. "application program interface"라는 용어는 1968년 AFIPS 논문 "Data structures and techniques for remote computer graphics"에 처음 기록되었다고 하며, 누가 만든 말인지는 해당 글에 밝혀져 있지 않습니다. 웹 개발에서는 HTTP 요청 메시지와 응답 구조(주로 XML 또는 JSON)를 정한 규격을 뜻하는 경우가 많아졌습니다. 이제 여섯 카드의 용어를 한 번의 요청 흐름으로 이어 보면 이렇습니다. 클라이언트가 엔드포인트(주소)에 HTTP 메서드로 요청하면서 API 키를 함께 보내고, 서버는 JSON 본문으로 응답하되 짧은 시간에 너무 많이 보내면 호출 제한에 걸려 거절합니다.

이웃 개념과 비교하기

REST 항목은 "RESTful"이라는 말이 흔히 HTTP 메서드 사용 관행을 가리키는데 이는 원래의 REST와 거리가 있고 때로는 상충한다고 설명합니다. 그러니 문서에 REST API라고 적혀 있어도 구체적인 규칙은 해당 서비스의 문서를 직접 확인해야 합니다.

실제 사례 세 가지

사례 1. 공공 데이터를 앱이 가져다 쓰는 구조: 기상청 단기예보 조회서비스 (공공 API의 사례)

공공데이터포털(data.go.kr)에는 기상청의 "단기예보 조회서비스"가 오픈 API(XML/JSON)로 등록되어 있습니다. 초단기 실황, 초단기 예보, 단기 예보, 예보 버전 정보를 조회하는 서비스로 소개됩니다. 사용하려면 포털에 로그인한 뒤 "활용신청"을 하고, 프로젝트용 또는 개인용 서비스키를 고르는 절차를 밟습니다. 이 서비스키가 API 키 역할을 합니다. 그러므로 날씨 앱이 직접 관측하지 않고 이런 공개 API를 호출해 화면을 만드는 구조는 실제로 가능하며, 서비스키로 호출자를 식별합니다. 다만 어떤 날씨 앱이 이 API를 쓰는지는 이 글에서 확인하지 않았고, 호출 한도는 확인한 페이지에 없어서 기재하지 않습니다. 배울 점은 API 키가 비밀번호라기보다 "누가 쓰는지 식별하는 이름표"이며, 공개 데이터라도 신청 절차를 거친다는 것입니다.

사례 2. 정책이 바뀌어 앱이 사라진 날: Reddit API 유료화 (운영 정책의 사례)

위키백과의 2023년 Reddit API 논란 항목에 따르면 Reddit은 2023년 4월 18일 API 사용에 요금을 부과하겠다고 발표했습니다. 서드파티 앱 Apollo를 만든 크리스천 셀리그는 6월 8일 앱을 6월 30일에 종료한다고 밝혔고, 5천만 요청에 1만 2천 달러를 제시받았으며 연간 최대 2천만 달러를 부담할 수 있다고 주장했습니다(이는 셀리그의 주장으로 기술됩니다). 6월 12일에는 수천 개의 서브레딧이 비공개로 전환하거나 게시를 제한하는 블랙아웃이 시작되었고, 처음 계획은 48시간이었으나 일부는 무기한으로 연장했습니다. 변경은 6월 30일에 시행되었다고 항목은 적고 있습니다. 배울 점은 API는 기술 문서만이 아니라 운영 정책에 묶여 있어서, 외부 API 위에 서비스를 만들면 요금·한도 변경이 사업 존립에 영향을 줄 수 있다는 점입니다. 호출당 요금은 확인한 자료에 없어 쓰지 않았습니다.

사례 3. 호출 제한을 표준으로 정리한 문서: RFC 6585의 429 (표준의 사례)

RFC 6585 4절은 HTTP 상태 코드 429 Too Many Requests를 정의합니다. 이는 사용자가 일정 시간에 너무 많은 요청을 보냈다("rate limiting")는 뜻입니다. 응답에는 얼마나 기다린 뒤 다시 요청하라는 Retry-After 헤더를 포함할 수 있다(MAY)고 적혀 있습니다. 위키백과 호출 제한 항목은 대표적 방식으로 토큰 버킷, 리키 버킷, 고정 윈도 카운터, 슬라이딩 윈도 로그, 슬라이딩 윈도 카운터의 이름을 나열합니다. 배울 점은 호출 제한이 서버 임의의 변덕이 아니라 표준화된 신호와 대응 방법(대기 후 재시도)이 있는 규칙이라는 점입니다. HTTP 상태 코드 가이드도 함께 보세요.

직접 읽어 보기: 가상 예시

아래는 실제 서비스가 아닌 가상 예시입니다. 요청과 응답이 어떻게 생겼는지 구조만 보여 줍니다.

요청: GET https://api.example.com/weather?city=seoul
헤더: Authorization 에 API 키를 담아 전송

응답(JSON):
{
  "city": "seoul",
  "temp": 18,
  "rain": false
}

주소 전체가 엔드포인트이고, 응답은 객체 하나입니다. JSON은 문자열을 큰따옴표로 감싸야 하고, 주석 문법이 없으며, 마지막 항목 뒤에 쉼표를 붙이면 유효하지 않습니다(위키백과 JSON 항목). 모양이 의심스러우면 JSON 포매터로 검사해 보세요. 요청 방식의 의미는 HTTP 메서드 완전정복에 정리되어 있습니다.

흔한 오해와 정정

• 오해: API는 곧 REST API다. 실제: REST는 API를 설계하는 한 스타일이며, API 자체는 훨씬 넓은 개념입니다(라이브러리의 명세도 API).
• 오해: JSON에는 주석을 달 수 있고 마지막 쉼표도 괜찮다. 실제: JSON은 주석 문법이 없고 마지막 항목 뒤 쉼표를 허용하지 않습니다. 더글러스 크록퍼드가 2000년대 초에 명세했고 첫 JSON 메시지는 2001년 4월에 전송되었으며, 현재 표준은 RFC 8259입니다.
• 오해: 호출 제한에 걸리면 계정이 영구 차단된 것이다. 실제: 429는 일정 시간에 너무 많이 보냈다는 신호이며 서버는 Retry-After로 대기 시간을 알려 줄 수 있습니다. 다만 서비스별 정책은 다르니 문서를 확인하세요.
• 오해: 공개 API는 신청 없이 누구나 쓴다. 실제: 기상청 단기예보처럼 활용신청 후 서비스키를 받는 경우가 많습니다. 이 글에서 확인한 사례는 이 하나이므로 모든 서비스가 그렇다는 뜻은 아닙니다.

한계와 더 알아볼 점

이 글은 개념 입문이며 인증 방식(OAuth 등), 버전 관리, 보안 설계는 다루지 않았습니다. 호출 제한의 알고리즘은 이름만 확인했고 동작 원리는 설명하지 않습니다. 사례 2의 금액은 개발자 측 주장이고, Reddit 측 입장과 정확한 요금표는 확인하지 못했습니다. 실제 서비스를 연동할 때는 해당 서비스의 최신 공식 문서와 이용약관을 기준으로 삼으세요.

HTTP 메서드도 궁금하다면

API 요청 방식이 궁금하다면 HTTP 메서드 완전정복, HTTP 상태 코드, JSON 포매터도 확인해보세요.

자주 묻는 질문