多年来,我已经为很多API实现了客户端。为此,我整理了一份清单,列出了一些可以改善开发体验的小技巧。这些想法大都与 API 设计或架构无关。这些技巧主要是给 API 的创建者提供帮助的,可以让客户端实现起来轻松一些。

让表格可下载、可解析

你有一个漂亮的自动生成的文档,其中有一堆包含错误代码、状态等列表的表格。请把这些列表做成CSVJSON或你喜欢的任何可解析格式,让它们可下载。永远不要把这些表格/列表的规范版本做成 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

余下全文(1/3)
分享这篇文章:

请关注我们:

《让 API 好用的 9 个小技巧》有1个想法

  1. admin  这篇文章, 并对这篇文章的反应是俺的神呀赞一个

发表评论

邮箱地址不会被公开。 必填项已用*标注