聚合国内IT技术精华文章,分享IT技术精华,帮助IT从业人士成长

让 API 好用的 9 个小技巧

2021-07-07 18:05 浏览: 2749117 次 我要评论(0 条) 字号:

作者 | edmz
译者 | 王强
策划 | 万佳

多年来,我已经为很多 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

本周好文推荐

程序员终结者还是“白嫖”开源代码?GitHub火爆新编程工具刚推出就陷入争议

Docker严重错误导致企业数据被黑客擦除,已存在七年之久

时隔6年重大更新,揭秘Windows 11如何做到原生支持安卓应用

两人小团队开发了一款与谷歌竞争的产品


InfoQ 写作平台欢迎所有热爱技术、热爱创作、热爱分享的内容创作者入驻!

还有更多超值活动等你来!

扫描下方二维码

填写申请,成为作者

开启你的创作之路吧~

点个在看少个 bug 



网友评论已有0条评论, 我也要评论

发表评论

*

* (保密)

Ctrl+Enter 快捷回复