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