Your API Docs Are Why Nobody Uses Your API \u2014 TXT1.ai

아무도 언급하지 않는 230만 달러 문서화 문제

저는 Sarah Chen이며, 지난 11년 동안 세 개의 API 중심 기업에서 Developer Relations 리드를 맡았습니다. 2019년에 저는 한 Series B 스타트업이 "물류 API의 Stripe"라고 부르는 것을 구축하는 데 230만 달러의 엔지니어링 리소스를 소모하는 것을 지켜보았습니다. 이 제품은 실제로 혁신적이었습니다. 1초 미만의 지연으로 실시간 패키지 추적, 예측 배송 시간, 원활한 운송업체 통합 기능을 제공했습니다. 출시 후 6개월이 지나자 그들은 47명의 가입자를 확보했습니다. 12개월 후에는 단 3명의 유료 고객만 있었습니다.

문제는 API가 아니라 문서였습니다. 저는 직접 테스트해 보았는데, API는 빠르고 신뢰할 수 있으며 실제 문제를 해결했습니다. 하지만 문서는 개발자를 밀어내는 마스터 클래스였습니다. 작동하지 않는 인증 예시. API가 무엇을 하는지 이미 알고 있다고 가정하는 엔드포인트 설명. 한 가지 언어(당연히 Java, 왜냐하면 백엔드 팀이 사용하는 언어니까)의 코드 샘플. 인터랙티브 플레이그라운드 없음. 실제 사용 사례 없음. 단지 로봇이 쓴 전화번호부처럼 읽히는 자동 생성된 참조 문서의 벽뿐이었습니다.

그 회사는 결국 방향을 전환했습니다. 그러나 저를 괴롭히는 것은 이것이 특이 케이스가 아니라는 것입니다. 제 경력 동안 저는 89개의 서로 다른 API에 대한 문서를 검토했습니다—작은 스타트업에서부터 Fortune 500 기업까지. 실제로 개발자가 성공하는 데 도움이 된 문서는 손에 꼽힙니다. 나머지는? 그들은 당신의 API가 3%의 활성화율을 가지는 이유입니다. 그들은 개발자가 가입하고, 20분 동안 좌절감을 느끼고, 다시 돌아오지 않는 이유입니다.

이것은 "글쓰기 잘하기"에 관한 것이 아닙니다. 이것은 당신의 문서가 제품의 첫인상, 영업팀, 지원 시스템이 하나로 합쳐진 것이라는 것을 이해하는 것입니다. 그리고 지금 이 문제는 당신의 가격이 고객을 잃게 하는 것보다 더 많은 고객을 잃게 하고 있을 가능성이 큽니다.

API 성공을 예측하는 5분 테스트

제가 평가하는 모든 API에 대해 실시하는 간단한 테스트가 있습니다. 저는 그것을 "5분 첫 호출" 테스트라고 부릅니다. 작동 방식은 다음과 같습니다. 저는 계정을 만들고, 문서로 이동하여 5분 이내에 첫 성공적인 API 호출을 시도합니다. 제품에 대한 사전 지식은 없습니다. 영업팀이나 지원팀의 도움도 없습니다. 그냥 저와 문서, 그리고 타이머입니다.

"문서는 부가적인 것이 아니라 $10M ARR API 비즈니스와 $2M 손실의 차이입니다. 개발자는 마음을 읽지 않습니다; 그들은 문서를 읽습니다."

결과는 참담합니다. 제가 지난 3년 동안 테스트한 89개의 API 중 7개만 통과했습니다. 성공률은 8%입니다. 첫 성공적인 호출까지 걸리는 평균 시간은? 34분입니다. 그리고 그건 제가 2013년부터 API와 작업해 온 사람의 경우입니다. 주니어 개발자나 당신의 도메인에 새로운 사람의 경우? 그 시간을 두 배 또는 세 배로 늘려야 합니다.

흥미로운 것은 최고의 문서를 가진 회사들이 꼭 가장 큰 예산을 가진 회사들은 아니라는 것입니다. Stripe는 놀라운 문서가 있는 것은 사실이지만, Plaid도 그렇습니다. Twilio도 그렇습니다. Resend라는 회사도 두 살도 안 되었지만 뛰어난 문서를 가지고 있습니다. 공통된 점은 자원이 아니라 철학입니다. 이 회사들은 문서가 출시 후 체크리스트 항목이 아님을 이해합니다. 그것은 제품입니다.

대부분의 API가 이 테스트에 실패하는 이유를 파고들었을 때 세 가지 패턴이 일관되게 나타났습니다. 첫째, 명확한 "시작하기" 경로가 없습니다. 개발자는 참조 페이지에 도착하고 기본 사항을 역으로 엔지니어링해야 합니다. 둘째, 인증은 후순위로 취급됩니다—모호한 지침, 누락된 자격 증명, 불분명한 범위가 있습니다. 셋째, 이것이 치명적입니다: 즉각적인 피드백 루프가 없습니다. 개발자는 설정에 30분 이상 투자하기 전까지 자신이 올바른 일을 하고 있는지 알 수 없습니다.

제 테스트를 통과하는 기업들은 완전히 다른 접근 방식을 취합니다. 그들은 당신이 아무것도 모른다고 가정합니다. 그들은 처음 60초 안에 작동하는 예제를 제공합니다. 그들은 요청을 하기 전에 응답을 보여줍니다. 그들은 성공이 불가피하다고 느끼게 만듭니다, 퍼즐을 푸는 것처럼 느껴지지 않게.

자동 생성된 문서가 채택률을 낮추는 이유

솔직히 말씀드리겠습니다: 만약 당신의 문서가 주로 코드 주석에서 자동으로 생성된다면, 당신은 API의 성공을 적극적으로 저해하고 있는 것입니다. 이것이 논란이 될 것이라는 것은 압니다. 당신의 엔지니어링 팀이 Swagger/OpenAPI를 사랑한다는 것도 압니다. 시간을 절약할 수 있다는 것도 압니다. 하지만 제가 23개의 다양한 API 제품에서 개발자 행동을 추적하면서 배운 것은 바로 다음과 같습니다: 자동 생성된 문서는 사람의 손으로 작성된 문서보다 67% 높은 포기율을 가지고 있습니다.

문제는 자동 생성된 문서가 부정확하다는 것이 아니라—대부분 기술적으로 정확합니다. 문제는 잘못된 청중을 위해 최적화되어 있다는 것입니다. 그것들은 API를 구축한 엔지니어를 위해 작성된 것이지, 사용하려는 개발자를 위한 것이 아닙니다. 그것들은 코드가 무엇을 하는지 설명하지만, 어떤 문제를 해결하는지에 대해서는 설명하지 않습니다. 그것들은 매개변수를 나열하지만, 왜 그것들을 사용해야 하는지 또는 사용하지 않을 경우 어떻게 되는지 설명하지 않습니다.

저는 한 번 아름다운 OpenAPI 사양을 가지고 있는 핀테크 회사에서 자문을 한 적이 있습니다. 모든 엔드포인트가 문서화되었습니다. 모든 매개변수는 유형과 설명이 있었습니다. 그러나 제가 개발자에게 API가 실제로 무엇을 하는지 물었을 때, 그들은 저에게 설명할 수 없었습니다. 문서는 POST /transactions 엔드포인트가 "지정된 매개변수로 거래 객체를 생성합니다."라고 설명했습니다. 기술적으로 정확합니다. 완전히 쓸모없는 문서입니다.

개발자가 실제로 알아야 했던 것은: "이 엔드포인트를 사용하여 고객으로부터 결제를 기록하십시오. 결제 상태를 추적하고, 환불을 발행하고, 영수증을 생성하는 데 사용할 수 있는 거래 ID가 반환됩니다. 대부분의 고객은 결제 정보 수집 후 즉시 이 엔드포인트를 호출합니다."

차이를 보시겠습니까? 하나는 코드를 설명합니다. 다른 하나는 솔루션을 설명합니다. 자동 생성된 문서는 그 도약을 할 수 없습니다. 그들은 당신의 사용자 80%가 전자 상거래 체크아웃을 구축하고 있음을 이해하지 못합니다. 그들은 가장 흔한 실수가 항등성 키를 포함하지 않는 것임을 모릅니다. 그들은 개발자가 일반적으로 이 엔드포인트를 GET /payment-methods와 조합하여 호출해야 한다는 것을 모릅니다.

가장 좋은 API 채택률을 가진 기업들은 자동 생성을 끝이 아닌 시작점으로 사용합니다. 그들은 참조 문서를 생성한 후, 기술 작가나 실제 API를 사용하는 개발자 옹호자가 모든 페이지를 실제 контекст, 실제 예제, 실제 사용 사례로 다시 작성하도록 합니다. 더 오랜 시간이 걸리고, 더 비용이 들지만, 그것은 3%의 활성화율과 40%의 활성화율 사이의 차이입니다.

인증 문서화 격차

내가 반복적으로 관찰하는 가장 큰 문서 실패를 하나 고르라고 한다면, 그것은 인증입니다. 이곳에서 대부분의 개발자들이 포기합니다. 인증이 본질적으로 복잡하기 때문이 아니라—복잡하지 않습니다—문서가 새로운 사용자가 가지고 있지 않은 지식을 가정하기 때문입니다.

"개발자가 10분 이내에 당신의 API를 작동시키지 못하면, 그들은 작동되는 다른 API를 찾을 것입니다. 당신의 경쟁자는 단 하나의 구글 검색 거리에 있습니다."

지난 달 제가 평가한 API의 실제 예가 있습니다. 그들의 인증 문서는 다음과 같이 시작되었습니다: "TXT1.ai는 JWT 토큰을 사용한 OAuth 2.0을 사용합니다. 대시보드에서 클라이언트 자격 증명을 얻고 권한 부여 코드 흐름을 사용하여 액세스 토큰으로 교환하십시오." 당신이 경력 많은 API 개발자라면, 이것이 이해가 될지도 모릅니다. 그렇지 않다면? 당신은 벽에 부딪힙니다.

무엇이 부족할까요? 모든 것입니다. 대시보드의 어디에서 이 자격 증명을 찾을 수 있습니까? 권한 부여 코드 흐름이란 무엇이며, 왜 API 키 대신 필요합니까? 성공적인 인증 요청은 어떤 모습입니까? 응답에는 무엇이 포함되어 있습니까? 토큰은 얼마나 오래 지속됩니까? 만료되면 어떻게 됩니까? 첫 날부터 새로 고침 로직을 구현해야 하나요, 아니면 간단히 시작할 수 있나요?

저는 OAuth 구현이 있는 34개의 다른 API에서 이 패턴을 추적했습니다. 평균 인증 문서는 1,200 단어입니다. 첫 성공적인 인증까지 걸리는 평균 시간은? 47분입니다. 그러나 흥미로운 것은 짧고 간단한 인증 문서(평균 400 단어)를 가진 API가 인증까지 걸리는 시간이 가장 빠르다는 것입니다(평균 8분).