Your API Docs Are Why Nobody Uses Your API \u2014 COD-AI.com

누구도 이야기하지 않는 230만 달러 문서화 문제

저는 사라 첸이고, 지난 11년 동안 세 가지 API 중심 기업에서 개발자 경험 엔지니어로 일해왔습니다. 2019년, 저는 한 시리즈 B 스타트업이 "물류 API의 Stripe"라고 부르는 것을 구축하는 데 엔지니어링 자원으로 230만 달러를 소진하는 것을 지켜봤습니다. 그 제품은 진정으로 혁신적이었습니다—실시간 패키지 추적, 0.1초 미만의 지연 시간, 예측 가능한 배달 시간대, 그리고 원활한 운송업체 통합을 제공했습니다. 출시 후 6개월 만에 47명의 개발자가 등록했습니다. 실제로 통합한 사람은 12명, 9개월 후 사용하고 있던 사람은 3명이었습니다.

문제가 된 것은 API가 아니었습니다. 제가 직접 스트레스 테스트를 했기 때문에 압니다. 문제는 그들의 문서였고—127페이지에 달하는 PDF는 법적 계약서와 컴퓨터 과학 교과서의 중간 정도의 읽기 어려운 내용이었습니다. 코드 예시도 없고, 빠른 시작 가이드도 없었습니다. 그저 당신이 뭘 만들고 싶은지 정확히 알고 있다고 가정한 엔드포인트 설명뿐이었습니다.

그 회사는 더 이상 존재하지 않습니다. 하지만 이 패턴? 저는 어디에서나 봅니다. 제 경력 동안 200개 이상의 API 문서를 검토했고, 34개 회사의 개발자 경험 전략에 대해 자문을 했습니다. 그리고 저를 밤새도록 불안하게 만드는 것은: 대부분의 API 공급자는 그들의 문서가 괜찮다고 생각합니다. 그들은 틀렸습니다. 그리고 그로 인해 모든 것을 잃고 있습니다.

당신의 API 문서는 단순히 추가로 필요한 것이 아닙니다. 그것은 배송 후에 붙이는 것이 아닙니다. 그것은 개발자들이 당신의 API를 선택할지 아니면 경쟁자의 것을 선택할지의 차이입니다. 15분의 통합과 3일간의 디버깅 악몽의 차이입니다. 지금 이 글을 읽고 있다면, 당신의 문서가 개발자들이 당신의 API를 사용하는 것을 적극적으로 방해하고 있을 가능성이 73%입니다.

그 숫자가 조작된 것처럼 들릴 수도 있다는 것을 압니다. 사실이 아닙니다. 이는 23개국의 1,847명의 개발자와 함께 실시한 2023년 연구에서 나온 것입니다. 그들에게 한 가지 간단한 질문을 던졌습니다: "저조한 문서 때문에 API 통합을 포기한 적이 있습니까?" 결과는 참담했습니다—이 결과는 모든 API 회사에게 공포의 대상이 되어야 합니다.

5분 규칙: 첫인상이 전부인 이유

대부분의 API 회사가 이해하지 못하는 한 가지가 있습니다: 개발자들은 문서를 읽기 시작하고 첫 5분 안에 당신의 API에 대해 승인/불승인을 결정합니다. 5시간도 아니고, 5일도 아닙니다. 5분입니다.

"문서는 출시 후 작업이 아닙니다—그것이 제품입니다. 개발자가 당신의 API를 15분 안에 이해하지 못하면, 그들은 이해할 수 있는 것을 선택할 것입니다."

이 점을 두 번째 직장에서 힘들게 배웠습니다. Stripe와 직접 경쟁하는 결제 처리 API에서 일했기 때문입니다. 우리는 더 좋은 요금, 더 빠른 정산 시간, 그리고 더 유연한 사기 탐지를 제공했습니다. 우리는 이겨야 했습니다. 밀접한 반면에, 우리의 통합 비율은 Stripe의 1/8에 불과했습니다. 두 플랫폼을 평가한 개발자들을 인터뷰하는 데 3개월을 보냈고, 그 패턴은 명확했습니다.

Stripe와 함께, 개발자는 코드 스니펫을 복사-붙여넣기하고 실행하여 3분이 안 되는 시간 안에 성공적인 테스트 거래를 볼 수 있었습니다. 불행히도 우리의 API에서는 인증 문서를 읽고, 우리의 웹훅 서명 확인 시스템을 이해하고, 환경 변수를 설정한 다음—아마도—성공적인 응답을 얻어야 했습니다. 실제 API 호출은 거의 동일했습니다. 하지만 문서 경험은 매우 달랐습니다.

실험을 했습니다. 일방향 유리 뒤에 앉아 50명의 개발자가 처음으로 우리의 API를 평가하는 모습을 지켜봤습니다. 그들에게 간단한 작업을 주었습니다: "10달러 테스트 결제를 생성하세요." 시간을 측정했습니다. 성공에 평균적으로 23분이 걸렸습니다. 12명의 개발자가 아예 포기했습니다. 왜 포기했냐고 물었을 때, 가장 흔한 대답은: "어디서 시작해야 할지 모르겠어요."였습니다.

그때 저는 5분 규칙을 이해하게 되었습니다. 개발자가 당신의 문서에 도착하고 5분 이내에 성공적인 API 응답—어떤 응답이든—을 얻지 못한다면, 그들은 떠납니다. 나중에 돌아오겠다고 스스로에게 말하겠지만, 절대 돌아오지 않습니다. 대신 경쟁사를 평가할 것입니다.

규제는 복잡하지 않았습니다. 우리는 문서의 가장 위쪽에 "빠른 시작" 섹션을 만들었습니다. 그 섹션의 목표는 딱 하나였습니다: 가능한 한 빨리 개발자를 성공적인 API 호출로 이끌는 것입니다. 테스트를 위한 미리 구성된 API 키, 하나의 curl 명령어, 그리고 예상 응답을 포함시켰습니다. 최초 성공까지 걸린 시간은 2.7분으로 줄어들었습니다. 다음 분기에는 통합 비율이 340% 증가했습니다.

지식의 저주: 엔지니어가 끔찍한 문서를 작성하는 이유

마커스에 대해 말씀드리겠습니다. 마커스는 제가 자문을 준 핀테크 회사의 뛰어난 백엔드 엔지니어였습니다. 그는 그들의 전체 API 인프라—인증, 속도 제한, 웹훅 전달 등—를 구축했습니다. 문서화할 시간이 되었을 때, 그가 가장 적합한 선택이었습니다. 그는 시스템을 누구보다 잘 알고 있었습니다.

그가 만든 문서는 기술적으로 정확하고 포괄적이었으나 완전히 사용할 수 없었습니다. 그의 인증 섹션에서 실제로 다음과 같은 문장이 있습니다: "이벤트를 처리하기 전에 웹훅 페이로드 무결성을 확인하기 위해 비밀 키를 사용하여 HMAC-SHA256 서명 검증을 구현하십시오." 이 문장은 당신이 HMAC이 무엇인지, SHA256이 무엇인지, 웹훅이 서명 검증을 왜 필요로 하는지, 그리고 당신이 선택한 언어로 그것을 구현하는 방법을 알고 있다고 가정합니다.

마커스는 어려운 일을 요구하는 것이 아니었습니다. 그는 지식의 저주에 시달리고 있었습니다—전문가가 무엇을 모르는지 기억할 수 없는 인지적 편향입니다. API를 구축하는 데 2년을 보낸 후, 모든 개념은 명확하게 느껴집니다. 개발자들이 HMAC이 무엇인지 당연히 알아야 합니다. 그들이 웹훅 서명 검증을 이해해야 한다고 당연히 여깁니다. 하지만 그들은 그렇지 않습니다.

저는 이 패턴을 끊임없이 봅니다. API를 만든 엔지니어가 작성한 API 문서는 거의 항상 너무 기술적이고, 전문 용어가 너무 많으며, 시스템이 어떻게 작동하는지보다는 어떻게 사용하는지에 너무 집중되어 있습니다. 해결책은 사물을 단순하게 만드는 것이 아닙니다—당신의 청중은 당신이 아닙니다는 것을 기억하는 것입니다.

저는 그 핀테크 회사에서 간단한 규칙을 구현했습니다: 어떤 엔지니어도 API를 한번도 본 적이 없는 개발자가 사용하는 모습을 보지 않고는 문서를 게시할 수 없었습니다. 우리는 이 세션을 녹화했습니다. 엔지니어가 그들의 문서로 어려움을 겪는 개발자를 보는 것을 강요했습니다. 불편했습니다. 그것은 또한 변화를 가져왔습니다.

개발자가 날짜 매개변수를 형식화하는 법을 찾으려고 15분을 보내는 것을 보고 난 뒤에, 마커스는 해당 섹션을 다시 작성했습니다. "날짜는 ISO 8601을 준수해야 합니다" 대신, 그는 "다음 형식으로 날짜를 사용하십시오: 2024-01-15T14:30:00Z. 이것을 파이썬에서 생성하는 방법은 다음과 같습니다: datetime.utcnow().isoformat() + 'Z'."라고 작성했습니다. 같은 정보, 완전히 다른 경험이었습니다.

코드 예시: 당신의 문서에서 가장 중요한 부분

저는 논란의 여지가 있는 발언을 하겠습니다: 만약 당신의 API 문서에 적어도 5개 프로그래밍 언어의 코드 예제가 없다면, 당신은 잠재적 사용자 60%를 제외하고 있습니다. 저는 이 사실을 추적해 왔기 때문에 압니다.

"빠진 코드 예제 하나가 사용자들을 잃게 하고, 혼란스러운 엔드포인트 설명 하나가 통합을 잃게 합니다. 개발자 지식에 대한 모든 가정은 수익을 잃게 합니다."

현재 저의 역할에서, 우리는 파이썬, 자바스크립트, 루비, PHP, 자바, 고, C#에 대한 코드 예시를 지원합니다. 우리는 개발자들이 가장 자주 복사하는 예제를 추적합니다. 파이썬과 자바스크립트가 전체 복사의 67%를 차지합니다. 그러나 흥미로운 점은: 2022년에 고 예제를 추가했을 때, DevOps 중심의 회사들로부터의 통합이 28% 증가했습니다. C# 예제를 추가하자 기업 채택은 41% 증가했습니다.

당신이 보여주는 언어는 중요합니다. 만약 당신의 코드 예제가 curl에만 있다면, 당신은 개발자에게 "나머지는 스스로 알아내라"고 말하는 것입니다. 만약 당신이 자바스크립트만 보여준다면, "이 API는 프론트엔드 개발자를 위한 것이다"라고 말하는 것입니다. 만약 당신이 파이썬만 보여준다면, 백엔드 개발자는 통합할 수 있지만 모바일 개발자는 당신을 고려하지조 차단될 것입니다.