永不过期的 API 密钥带来的问题
一个多年前签发、从未轮换、至今仍然有效的密钥并不是一种便利。它是一个多年来没有人真正检查过的隐患。
为什么文档质量比功能数量更重要
列出四十个端点的价格页面，看起来比只列出十五个的更强大。但它往往也是一个警示信号。构建一个端点只占让它变得可用的工作量的一小部分。其余的是文档：清晰的参数说明、真实的请求和响应示例、如实的边界情况说明，以及对出错时会发生什么的通俗解释。如果在四十个端点上都跳过这些工作，您得到的就是四十个在技术上存在、在实际中几乎不存在的功能。
我们宁愿少做一些事情并把它们写好文档，也不愿多做一些事情却把文档写得很差。评估 API 的开发者很少先读功能列表。他们会读文档，尝试一个示例请求，然后在最初几分钟内，根据这个示例是否真的能按所写的那样运行，形成对整家公司的看法。如果不能，营销页面上的功能数量就不再重要了，因为继续读下去所需的信任已经离场。
对我们来说，好的文档意味着几件具体的事情，而不是一句含糊的承诺。它意味着身份验证的说明会清楚列出每一种可接受的方式，而不只是服务商偏好的那一种。它意味着速率限制以真实的数字说明，而不是“适用宽松的限制”。它意味着错误代码会连同实际引发每个错误的原因一起列出，这样调试失败请求的开发者就能在文档中找到答案，而不是仅凭一个状态码去猜。这些都不需要更多的工程工作。它需要的是有人认定，把事情清楚地写下来不是附加在真正产品上的可有可无的杂务。
仅仅勉强够用的文档还有一种会不断累积的成本。在文档中找不到答案的开发者会提交支持工单，于是解决这一个问题，在构建功能已经花掉的工程时间之外，还要再耗费员工的时间。把这乘以足够多卡在同一段含糊文字上的客户，编写单薄文档所“节省”的成本很快就会变成负数。清晰的文档不是叠加在 API 之上的锦上添花。一旦把一段含糊文字所带来的支持负担计算在内，它比另一种选择更便宜。
我们还认为，文档质量是潜在客户在决定集成之前真正能够评估的少数信号之一。您无法在五分钟内轻松检验一家服务商的正常运行时间记录，也无法在集成之前全面判断数据准确性。但您可以在五分钟内读完文档，判断撰写文档的公司是否足够了解自己的产品、能把它讲清楚，还是说这些文档读起来就像是事后硬接在一份为销售页面打造的功能列表上的附属品。
一份长长的功能列表很容易写。能让开发者第一次尝试就据此构建成功的文档却不容易写，而这种差别正是它更重要的原因。