API란 무엇인가?

API(Application Programming Interface)는 코드로 작성된 약속입니다.

"이렇게 물어보시면, 이렇게 답해드리겠습니다. 그리고 경고 없이 규칙을 바꾸지 않겠습니다."라는 계약입니다.

버튼을 탭할 때마다 한 번도 본 적 없는 서버에서, 한 번도 만난 적 없는 사람들이 운영하는 곳에서 무언가가 일어납니다—이때 당신은 API가 약속을 지킬 것이라고 신뢰하는 겁니다. 그 신뢰가 하루에 수십억 건의 요청으로 곱해지면, 현대 인터넷이 가능해집니다.

"인터페이스"라는 단어

인터페이스는 두 가지가 만나서 상호작용하는 경계입니다. 자동차 핸들은 당신과 차량 메커니즘 사이의 인터페이스입니다. 파워 스티어링이 어떻게 작동하는지 이해하지 않아도 왼쪽으로 꺾을 수 있죠.

API도 같은 방식으로 작동합니다. 날씨 API를 이용하면 데이터가 어떻게 수집됐는지, 어디에 저장됐는지, 어떤 알고리즘으로 예측했는지 몰라도 내일의 날씨를 요청할 수 있습니다. 그냥 물어보면 됩니다. API가 답해줍니다.

인터페이스는 복잡성을 숨기고 기능을 드러냅니다.

API가 실제로 작동하는 방식

API는 요청과 응답을 통해 작동합니다. 한 시스템(클라이언트)이 무언가를 요청합니다. 다른 시스템(서버)이 그것을 제공합니다.

날씨 앱이 내일의 날씨를 보여줄 때, 다음과 같은 일이 일어납니다:

1. 앱이 날씨 서비스에 요청을 보냅니다: "이 위치의 날씨 예보는?"
2. 날씨 서비스가 요청을 받아 데이터를 조회해 정리합니다
3. 서비스가 날씨 예보와 함께 응답을 돌려보냅니다
4. 앱이 보기 좋은 화면에 표시합니다

앱은 날씨 서비스의 데이터베이스에 직접 접근하지 않습니다. 날씨가 어떻게 계산됐는지도 알지 못합니다. 단지 API를 통해 질문하고 답을 받은 것뿐입니다.

웹 API의 구조

대부분 접하게 되는 API는 웹 API입니다—브라우저가 사용하는 것과 같은 프로토콜인 HTTP로 통신합니다. 웹 API는 다음으로 구성됩니다:

엔드포인트는 요청을 보내는 주소입니다. https://api.weather.com/forecast나 https://api.stripe.com/charges처럼요. 각 엔드포인트는 특정 작업을 수행합니다.

메서드는 수행하려는 작업을 나타냅니다:

• GET: 데이터 조회
• POST: 새 데이터 생성
• PUT: 기존 데이터 수정
• DELETE: 데이터 삭제

파라미터는 세부 정보를 제공합니다. "날씨 예보 조회"가 "위도 37.7749, 경도 -122.4194, 화씨 단위로 날씨 예보 조회"가 되는 거죠.

헤더는 메타데이터를 전달합니다—인증 토큰, 콘텐츠 유형, 캐싱 지침 등.

요청 본문은 전송하는 데이터를 담습니다. 보통 JSON 형식입니다.

응답 본문은 돌아오는 데이터를 담습니다. 이것도 보통 JSON입니다.

상태 코드는 무슨 일이 있었는지 알려줍니다: 200은 성공, 404는 찾을 수 없음, 500은 서버 오류입니다.

API가 모든 것을 바꾼 이유

모든 것을 직접 만들 필요가 없습니다. 결제 처리가 필요하다면? Stripe API를 사용하세요. 문자 메시지를 보내고 싶다면? Twilio API. 지도가 필요하다면? Google Maps API. 이 회사들은 수년간 인프라를 구축했고, 당신은 몇 줄의 코드로 그것에 접근할 수 있습니다.

시스템이 전문화될 수 있습니다. 하나의 거대한 애플리케이션 대신, 인증, 결제, 알림, 검색 등 각각의 API를 갖춘 집중적인 서비스들을 구축할 수 있습니다. 서로 얽히지 않고도 함께 작동합니다.

구현을 바꿔도 클라이언트가 깨지지 않습니다. API 약속이 지켜지는 한—같은 엔드포인트, 같은 데이터 형식, 같은 동작—백엔드를 완전히 다시 작성해도 됩니다. API를 사용하는 누구도 눈치채지 못합니다.

플랫폼이 생태계가 됩니다. Twitter, Stripe, Shopify, Salesforce—모두 개발자들이 API를 통해 그 위에 무언가를 구축할 수 있게 되면서 더 가치 있어졌습니다. API가 제품을 플랫폼으로 바꿔놓은 겁니다.

공개 API, 비공개 API, 파트너 API

공개 API는 누구나 사용할 수 있습니다. GitHub API를 사용하면 어떤 개발자든 저장소와 상호작용하는 도구를 만들 수 있습니다. 이런 API는 훌륭한 문서, 철저한 하위 호환성, 강력한 남용 방지가 필요합니다—변경 사항이 수천 명의 외부 개발자에게 영향을 미치니까요.

비공개 API는 조직 내부에 존재합니다. 회사의 서비스들은 외부에서는 볼 수 없는 내부 API를 통해 서로 통신합니다. 사용자가 모두 자체 팀이므로 더 빠르게 발전할 수 있습니다.

파트너 API는 그 사이 어딘가에 있습니다—특별한 접근 권한과 요청 제한으로, 계약을 맺은 특정 비즈니스 파트너와 공유됩니다.

약속으로서의 API

API에서 가장 중요한 것은 기술이 아닙니다. 바로 계약입니다.

API를 공개하면, 당신은 약속을 하는 겁니다:

• 이 엔드포인트들이 존재할 것입니다
• 이 파라미터들을 받을 것입니다
• 이 형식으로 데이터를 반환할 것입니다
• 이런 방식으로 동작할 것입니다
• 무언가를 변경해야 할 때, 미리 알려드리겠습니다

이 약속을 어기면 신뢰가 깨집니다. 당신의 API 위에 구축된 애플리케이션이 깨집니다. 당신의 시스템을 배우는 데 시간을 투자한 개발자들이 피해를 입습니다.

잘 설계된 API는 계약을 신성하게 여깁니다. 신중하게 버전을 관리합니다. 점진적으로 기능을 폐기합니다. 변경 사항을 명확하게 전달합니다. API는 단순한 코드가 아니라—그것에 의존하는 모든 사람과의 관계이기 때문입니다.

좋은 API의 조건

일관성. GET /users가 사용자 목록을 반환한다면, GET /posts는 게시물 목록을 반환해야 합니다. 패턴은 예측 가능해야 합니다.

명확한 이름. /users가 /u보다 낫습니다. getUserProfile이 getUP보다 낫습니다. 이름은 스스로 설명해야 합니다.

솔직한 오류. 무언가 실패했을 때, 오류 메시지는 무엇이 잘못됐는지, 가능하다면 어떻게 고치는지 설명해야 합니다. "잘못된 요청"은 아무에게도 도움이 안 됩니다. "필수 필드 누락: email"은 모두에게 도움이 됩니다.

실질적인 문서. 작동하는 예시를 보여주세요. 모든 파라미터를 설명하세요. 응답 예시를 포함하세요. 오류 상황을 문서화하세요. 문서가 없는 API는 쓸모없는 API입니다.

처음부터 보안. 인증을 요구하세요. 입력을 검증하세요. HTTPS를 사용하세요. 일반적인 공격으로부터 보호하세요. 보안은 나중에 추가하는 기능이 아닙니다.

꼭 알아야 할 API 유형

웹 API는 대부분의 사람들이 2024년에 "API"라고 말할 때 의미하는 것입니다. HTTP를 사용하고, JSON을 반환하며, 인터넷 전반에 걸쳐 애플리케이션과 서비스 간의 연동을 지원합니다.

라이브러리 API는 프로그래밍 언어와 프레임워크가 노출하는 인터페이스입니다. JavaScript에서 array.map()을 호출할 때, API를 사용하는 겁니다—"함수를 주면, 각 요소에 적용하겠습니다"라는 계약.

운영체제 API는 프로그램이 OS와 상호작용할 수 있게 해줍니다—창 만들기, 파일 읽기, 네트워크 접근 등.

데이터베이스 API는 애플리케이션이 데이터를 조회하고 수정할 수 있게 합니다. SQL 자체가 일종의 API입니다.

하드웨어 API는 카메라, GPS, 가속도계 같은 장치에 접근할 수 있게 합니다.

모두 인터페이스입니다. 모두 약속을 합니다. 웹 API는 그중에서 인터넷을 연결하는 것입니다.

API 경제

API가 제품이 됐습니다.

Stripe의 API는 수십억 달러의 매출을 만들어냅니다. Twilio의 API는 전 세계 기업들의 통신을 지원합니다. AWS는 컴퓨팅, 스토리지, AI 등 수십 가지 서비스에 대한 API 접근을 판매합니다.

"API 경제"는 기능을 프로그래밍 방식의 인터페이스를 통해 사고파는 생태계입니다. 기업이 기능을 노출합니다. 개발자가 애플리케이션을 구축합니다. 연결을 통해 가치가 흐릅니다.

이것은 진정으로 새로운 현상입니다. 20년 전, 결제 처리가 필요하다면 은행과 계약을 협상하고 커스텀 연동을 구축해야 했습니다. 이제는 Stripe 문서를 읽고, 몇 줄의 코드를 작성하면, 내일까지 결제를 처리할 수 있습니다.

API는 기능을 조합 가능하게 만들었습니다. 그것이 모든 것을 바꿨습니다.

API에 대해 자주 묻는 질문

API와 웹사이트의 차이는 무엇인가요?

웹사이트는 사람을 위한 것입니다—브라우저가 시각적인 페이지로 렌더링하는 HTML을 반환합니다. API는 프로그램을 위한 것입니다—코드가 처리할 수 있는 구조화된 데이터(보통 JSON)를 반환합니다. 많은 서비스는 둘 다 제공합니다: 방문할 수 있는 웹사이트와 애플리케이션이 호출할 수 있는 API.

API를 사용하려면 코딩을 알아야 하나요?

애플리케이션에 API를 통합하려면 그렇습니다—프로그래밍 능력이 필요합니다. 하지만 이제 많은 도구들이 비프로그래머도 시각적 인터페이스(Zapier, Make 등)를 통해 API를 연결할 수 있게 합니다. 그리고 API가 어떻게 작동하는지 이해하면 현대 소프트웨어 시스템이 어떻게 연결되는지 누구나 파악할 수 있습니다.

API에 요청 제한(rate limit)이 있는 이유는 무엇인가요?

요청 제한은 남용을 방지하고 공정한 접근을 보장합니다. 한 사용자가 무제한으로 요청할 수 있다면, 서비스를 압도해서 다른 모든 사람에게 서비스 품질을 저하시킬 수 있습니다. 요청 제한은 "분/시간/일당 X번 요청할 수 있습니다"라고 말합니다—정당한 사용에는 충분하지만 문제를 일으킬 정도는 아닙니다.

API가 변경되면 어떻게 되나요?

잘 설계된 API는 변경 사항에 버전을 붙입니다. "v1"을 유지하면서 "v2"를 출시해 개발자들이 마이그레이션할 시간을 줄 수 있습니다. 경고 없는 변경은 애플리케이션과 신뢰를 깨뜨립니다. 최고의 API는 하위 호환성을 진지한 약속으로 여깁니다.

API는 안전한가요?

API는 어떻게 구축되느냐에 따라 안전할 수도, 안전하지 않을 수도 있습니다. 좋은 API는 인증을 요구하고, 전송 중 데이터를 암호화하고, 입력을 검증하고, 보안 모범 사례를 따릅니다. 하지만 모든 소프트웨어처럼 API도 취약점을 가질 수 있습니다. 결국 API를 신뢰한다는 건 그 뒤에 있는 조직을 신뢰하는 것입니다—그 조직이 받을 자격이 있는 만큼만 신뢰하세요.