让 API 好用的 9 个小技巧
source link: https://www.techug.com/post/nine-tips-to-make-api-easy-to-use.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
让 API 好用的 9 个小技巧
多年来，我已经为很多API实现了客户端。为此，我整理了一份清单，列出了一些可以改善开发体验的小技巧。这些想法大都与 API 设计或架构无关。这些技巧主要是给 API 的创建者提供帮助的，可以让客户端实现起来轻松一些。
让表格可下载、可解析
你有一个漂亮的自动生成的文档，其中有一堆包含错误代码、状态等列表的表格。请把这些列表做成CSV、JSON或你喜欢的任何可解析格式，让它们可下载。永远不要把这些表格/列表的规范版本做成 PDF 格式。
这也适用于样本响应。
添加 echo/测试方法
有时你只需要测试 API 是否活跃、工作正常。而且你手头可能没有文档，或者由于 API 的性质，调用一个仅用于测试和端点的方法可能会很复杂。在这些情况下，一个可以通过 curl 调用的“echo”函数是很好用的。
加入你的主要用例的示例
并非所有 API 方法都是平等的。大多数人只需要实现一定数量的方法。这些方法可能会按特定顺序调用。请在文档中加入主要用例的伪代码。
搞清楚时间
我很少看到有文档会声明预期响应时间。你用不着把具体的秒数指定为 SLA，只需暗示这个或那个特定函数可能需要比预期更长的时间就行了。
加入错误/状态描述
当事情不正常时，grep 日志的用户可能并不是为 API 实现客户端的作者。加入用户可以理解的状态或错误代码的文本描述是很有用的，可以帮助用户更快地解决问题。
隐藏你的错误，但提供足够的反馈数据
我见过有的 API 的错误代码只考虑到了 API 背后的团队。
API 用户不关心诸如“数据库错误”“用户配置错误”“锁定超时”之类的错误。请换种方式标记它们并在错误描述中添加注释，告诉用户联系支持。
为复杂转换加上各步的原始数据
出于某种原因，你需要用户通过一系列步骤 concat、哈希和加密一些数据吗？你有一个需要以特定方式破坏数据的算法吗？请添加示例数据，告诉用户每个步骤中具体的转换方法。并非所有语言都有以相同方式工作或接收相同参数的库。如果能有一种方法可以逐步重现复杂的步骤，对那些必须从头开始编写代码的用户来说会有很大帮助。
列出常见问题
实现你的 API 时最困难的部分是什么？人们最常问哪些问题？请将它们添加为文档中相关函数的注释，或者其他合适的位置。
让用户知道如何联系到你
大多数 API 文档都没有写上咨询 API 技术问题的联系方式。有时，你只能会在网站上搜索联系方式或写一封电子邮件至 support@whatever，最后才能与可以回答 API 相关问题的人取得联系。如果可以，请告诉用户如何与可以实际回答 API 相关问题的人取得联系。
原文链接：
https://edmz.org/personal/2021/05/27/small_things_that_make_apis_a_little_bit_better.html
本文文字及图片出自 InfoQ
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK