让 API 好用的9个小技巧

作者 | 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