作者 | edmz
譯者 | 王強
策劃 | 萬佳
多年來，我已經為很多 API 實現了客戶端。為此，我整理了一份清單，列出了一些可以改善開發體驗的小技巧。這些想法大都與 API 設計或架構無關。這些技巧主要是給 API 的創建者提供幫助的，可以讓客戶端實現起來輕松一些。
1. 讓表格可下載、可解析
你有一個漂亮的自動生成的文檔，其中有一堆包含錯誤代碼、狀態等列表的表格。請把這些列表做成 CSV、JSON 或你喜歡的任何可解析格式，讓它們可下載。永遠不要把這些表格 / 列表的規范版本做成 PDF 格式。
這也適用于樣本響應。
2. 添加 echo/ 測試方法
有時你只需要測試 API 是否活躍、工作正常。而且你手頭可能沒有文檔，或者由于 API 的性質，調用一個僅用于測試和端點的方法可能會很復雜。在這些情況下，一個可以通過 curl 調用的“echo”函數是很好用的。
3. 加入你的主要用例的示例
并非所有 API 方法都是平等的。大多數人只需要實現一定數量的方法。這些方法可能會按特定順序調用。請在文檔中加入主要用例的偽代碼。
4. 搞清楚時間
我很少看到有文檔會聲明預期響應時間。你用不著把具體的秒數指定為 SLA，只需暗示這個或那個特定函數可能需要比預期更長的時間就行了。
5. 加入錯誤 / 狀態描述
當事情不正常時，grep 日志的用戶可能并不是為 API 實現客戶端的作者。加入用戶可以理解的狀態或錯誤代碼的文本描述是很有用的，可以幫助用戶更快地解決問題。
6. 隱藏你的錯誤，但提供足夠的反饋數據
我見過有的 API 的錯誤代碼只考慮到了 API 背后的團隊。
API 用戶不關心諸如“數據庫錯誤”“用戶配置錯誤”“鎖定超時”之類的錯誤。請換種方式標記它們并在錯誤描述中添加注釋，告訴用戶聯系支持。
7. 為復雜轉換加上各步的原始數據
出于某種原因，你需要用戶通過一系列步驟 concat、哈希和加密一些數據嗎？你有一個需要以特定方式破壞數據的算法嗎？請添加示例數據，告訴用戶每個步驟中具體的轉換方法。并非所有語言都有以相同方式工作或接收相同參數的庫。如果能有一種方法可以逐步重現復雜的步驟，對那些必須從頭開始編寫代碼的用戶來說會有很大幫助。
8. 列出常見問題
實現你的 API 時最困難的部分是什么？人們最常問哪些問題？請將它們添加為文檔中相關函數的注釋，或者其他合適的位置。
9. 讓用戶知道如何聯系到你
大多數 API 文檔都沒有寫上咨詢 API 技術問題的聯系方式。有時，你只能會在網站上搜索聯系方式或寫一封電子郵件至 support@whatever，最后才能與可以回答 API 相關問題的人取得聯系。如果可以，請告訴用戶如何與可以實際回答 API 相關問題的人取得聯系。
原文鏈接：
https://edmz.org/personal/2021/05/27/small_things_that_make_apis_a_little_bit_better.html
