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

Vấn đề tài liệu 2,3 triệu đô la mà không ai nói đến

Tôi là Sarah Chen, và tôi đã dành 11 năm qua làm trưởng phòng Quan hệ Nhà phát triển tại ba công ty API-first khác nhau. Vào năm 2019, tôi đã chứng kiến một công ty khởi nghiệp Series B tiêu tốn 2,3 triệu đô la vào nguồn lực kỹ thuật để xây dựng cái mà họ gọi là "Stripe của các API logistics." Sản phẩm thực sự đổi mới—theo dõi gói hàng theo thời gian thực với độ trễ dưới một giây, khoảng thời gian giao hàng dự đoán, và tích hợp nhà vận chuyển liền mạch. Sáu tháng sau khi ra mắt, họ có 47 lượt đăng ký. Mười hai tháng sau, chỉ có 3 khách hàng trả phí.

API không phải là vấn đề. Tôi đã tự kiểm tra—nó nhanh, đáng tin cậy, và giải quyết những vấn đề thực tế. Tuy nhiên, tài liệu lại là một lớp học mẫu mực về việc làm mất lòng các nhà phát triển. Những ví dụ xác thực không hoạt động. Những mô tả điểm cuối giả định rằng bạn đã biết API làm gì. Những mẫu mã chỉ bằng một ngôn ngữ (Java, tất nhiên, vì đó là ngôn ngữ mà nhóm backend sử dụng). Không có sân chơi tương tác. Không có trường hợp sử dụng thực tế. Chỉ là một bức tường tài liệu tham khảo tự động tạo ra, đọc như một cuốn danh bạ viết bởi robot.

Công ty đó cuối cùng đã chuyển hướng. Nhưng đây là điều khiến tôi ám ảnh: đây không phải là một trường hợp ngoại lệ. Trong sự nghiệp của tôi, tôi đã xem xét tài liệu cho 89 API khác nhau—từ những công ty khởi nghiệp nhỏ đến những công ty Fortune 500. Tôi có thể đếm trên một bàn tay số lượng mà thực sự giúp các nhà phát triển thành công. Phần còn lại? Đó là lý do tại sao API của bạn có tỷ lệ kích hoạt 3%. Đó là lý do tại sao các nhà phát triển đăng ký, mất 20 phút để cảm thấy thất vọng, và không bao giờ trở lại.

Điều này không phải là về việc "giỏi viết lách." Nó liên quan đến việc hiểu rằng tài liệu của bạn là ấn tượng đầu tiên của sản phẩm, đội ngũ bán hàng của bạn, và hệ thống hỗ trợ của bạn tất cả gộp vào một. Và ngay bây giờ, nó có thể đang khiến bạn mất nhiều khách hàng hơn giá cả của bạn bao giờ hết.

Bài kiểm tra năm phút dự đoán thành công API

Tôi có một bài kiểm tra đơn giản mà tôi thực hiện trên mọi API mà tôi đánh giá. Tôi gọi nó là bài kiểm tra "Cuộc gọi đầu tiên năm phút." Đây là cách nó hoạt động: tôi tạo một tài khoản, điều hướng đến tài liệu, và cố gắng thực hiện cuộc gọi API thành công đầu tiên trong vòng năm phút. Không có kiến thức trước về sản phẩm. Không có sự trợ giúp từ bán hàng hay hỗ trợ. Chỉ có tôi, tài liệu, và một cái đồng hồ bấm giờ.

"Tài liệu không phải là thứ cần có—nó là sự khác biệt giữa một doanh nghiệp API 10 triệu đô la ARR và một khoản chi 2 triệu đô la không cần thiết. Các nhà phát triển không đọc tâm trí; họ đọc tài liệu."

Kết quả thật đáng thất vọng. Trong số 89 API tôi đã thử nghiệm trong ba năm qua, chỉ có 7 API đạt yêu cầu. Đó là tỷ lệ thành công 8%. Thời gian trung bình để có cuộc gọi thành công đầu tiên? 34 phút. Và điều đó đến từ một người đã làm việc với các API từ năm 2013. Đối với một nhà phát triển junior hoặc ai đó mới làm quen với miền của bạn? Nhân đôi hoặc gấp ba thời gian đó.

Điều thú vị là các công ty có tài liệu tốt nhất không nhất thiết là những công ty có ngân sách lớn nhất. Stripe có tài liệu tuyệt vời, chắc chắn, nhưng Plaid cũng vậy. Twilio cũng vậy. Resend, một công ty được ra mắt chưa đầy hai năm trước cũng vậy. Sợi chỉ chung không phải là nguồn lực—mà là triết lý. Những công ty này hiểu rằng tài liệu không phải là một mục cần kiểm tra sau khi ra mắt. Đó chính là sản phẩm.

Khi tôi tìm hiểu lý do tại sao hầu hết các API không vượt qua bài kiểm tra này, ba mẫu hình xuất hiện một cách nhất quán. Thứ nhất, không có lộ trình "bắt đầu" rõ ràng. Các nhà phát triển đến một trang tham khảo và phải đảo ngược kỹ thuật cơ bản. Thứ hai, xác thực được xem như là một suy nghĩ muộn màng—hướng dẫn mơ hồ, thiếu thông tin xác thực, phạm vi không rõ ràng. Thứ ba, và đây là điều chết người: không có vòng phản hồi ngay lập tức. Các nhà phát triển không thể biết liệu họ có thực hiện đúng hay không cho đến khi họ đã đầu tư hơn 30 phút vào việc thiết lập.

Các công ty vượt qua bài kiểm tra của tôi làm điều gì khác biệt một cách mạnh mẽ. Họ giả định rằng bạn không biết gì cả. Họ cung cấp cho bạn một ví dụ hoạt động trong 60 giây đầu tiên. Họ cho bạn thấy phản hồi trước khi bạn thậm chí thực hiện yêu cầu. Họ làm cho thành công cảm thấy chắc chắn, chứ không như giải quyết một câu đố.

Tại sao tài liệu tự động tạo ra đang giết chết sự chấp nhận của bạn

Hãy để tôi nói thẳng: nếu tài liệu của bạn chủ yếu được tự động tạo ra từ các bình luận trong mã, bạn đang tự sabotaga sự thành công của API của mình. Tôi biết điều này là gây tranh cãi. Tôi biết đội ngũ kỹ thuật của bạn yêu thích Swagger/OpenAPI. Tôi biết nó tiết kiệm thời gian. Nhưng đây là điều tôi đã học từ việc theo dõi hành vi của các nhà phát triển trên 23 sản phẩm API khác nhau: tài liệu tự động tạo ra có tỷ lệ bỏ đi cao hơn 67% so với tài liệu do con người tạo ra.

Vấn đề không phải là tài liệu tự động tạo ra không chính xác—chúng thường chính xác về mặt kỹ thuật. Vấn đề là chúng được tối ưu hóa cho đối tượng sai. Chúng được viết cho kỹ sư đã xây dựng API, không phải cho nhà phát triển đang cố gắng sử dụng nó. Chúng mô tả những gì mã làm, không phải những vấn đề mà nó giải quyết. Chúng liệt kê các tham số mà không giải thích tại sao bạn nên sử dụng chúng hoặc điều gì xảy ra khi bạn không sử dụng.

Tôi đã từng tư vấn cho một công ty fintech có đặc điểm OpenAPI tuyệt đẹp. Mỗi điểm cuối đều được tài liệu. Mỗi tham số có kiểu và mô tả. Nhưng khi tôi hỏi các nhà phát triển API thực sự làm gì, họ không thể nói cho tôi biết. Tài liệu giải thích rằng điểm cuối POST /transactions "tạo ra một đối tượng giao dịch với các tham số đã chỉ định." Về mặt kỹ thuật là đúng. Hoàn toàn vô dụng.

Những gì các nhà phát triển thực sự cần biết: "Sử dụng điểm cuối này để ghi nhận một khoản thanh toán từ khách hàng của bạn. Bạn sẽ nhận được một ID giao dịch mà bạn có thể sử dụng để theo dõi trạng thái thanh toán, phát hành hoàn tiền hoặc tạo biên lai. Hầu hết khách hàng gọi điểm cuối này ngay sau khi thu thập thông tin thanh toán từ quy trình thanh toán của họ."

Bạn thấy sự khác biệt không? Một cái mô tả mã. Cái kia mô tả giải pháp. Tài liệu tự động tạo ra không thể làm được bước nhảy vì chúng không hiểu bối cảnh. Chúng không biết rằng 80% người dùng của bạn đang xây dựng các quy trình thanh toán thương mại điện tử. Chúng không biết sai lầm phổ biến nhất là quên bao gồm khóa idempotency. Chúng không biết rằng các nhà phát triển thường cần gọi điểm cuối này kết hợp với GET /payment-methods.

Các công ty có tỷ lệ chấp nhận API tốt nhất sử dụng tự động hóa như một điểm khởi đầu, không phải điểm kết thúc. Họ tạo ra tài liệu tham khảo, sau đó họ yêu cầu các nhà văn kỹ thuật—hoặc nhà quảng bá nhà phát triển thực sự sử dụng API—viết lại từng trang với bối cảnh thực, ví dụ thực và trường hợp sử dụng thực. Điều này mất nhiều thời gian hơn. Tốn kém hơn. Nhưng đó là sự khác biệt giữa tỷ lệ kích hoạt 3% và 40%.

Khoảng trống tài liệu xác thực

Nếu tôi phải chọn một thất bại tài liệu lớn nhất mà tôi thấy lặp đi lặp lại, đó là xác thực. Đây là nơi hầu hết các nhà phát triển bỏ cuộc. Không phải vì xác thực vốn đã phức tạp—mà vì tài liệu giả định kiến thức mà người dùng mới không có.

"Nếu một nhà phát triển không thể khiến API của bạn hoạt động trong vòng 10 phút, họ sẽ tìm một cái mà họ có thể. Cạnh tranh của bạn chỉ cách một tìm kiếm Google."

Đây là một ví dụ thực tế từ một API mà tôi đánh giá vào tháng trước. Tài liệu xác thực của họ bắt đầu với: "TXT1.ai sử dụng OAuth 2.0 với token JWT. Lấy thông tin xác thực của bạn từ bảng điều khiển và trao đổi chúng để nhận token truy cập thông qua luồng mã ủy quyền." Nếu bạn là một nhà phát triển API có kinh nghiệm, điều này có thể hợp lý. Nếu bạn không phải? Bạn vừa gặp một bức tường.

Điểm thiếu sót? Mọi thứ. Đúng vị trí nào trong bảng điều khiển tôi tìm thấy những thông tin xác thực này? Luồng mã ủy quyền là gì, và tại sao tôi cần nó thay vì chỉ sử dụng một khóa API? Một yêu cầu xác thực thành công trông như thế nào? Phản hồi chứa gì? Token tồn tại trong bao lâu? Điều gì xảy ra khi nó hết hạn? Tôi có cần triển khai logic làm tươi vào ngày đầu tiên, hay tôi có thể bắt đầu đơn giản?

Tôi đã theo dõi mẫu này trên 34 API khác nhau với các triển khai OAuth. Tài liệu xác thực trung bình dài 1.200 từ. Thời gian trung bình đến xác thực thành công đầu tiên? 47 phút. Nhưng đây là điều thú vị: các API có tài liệu xác thực ngắn gọn và đơn giản nhất (trung bình 400 từ) lại có thời gian xác thực nhanh nhất (trung bình 8 phút).