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