API设计的七宗罪( 二 ) _API

{"properties": [{"id": 4478,"rooms": [{"id": 12328,"available": false}]},{"id": 5729,"rooms": [{"id": 13219,"available": false}]},{"id": 6779,"rooms": [{"id": 14900,"available": true}]}],"checkIn": "2019-05-01","lastNight": "2019-05-02","checkOut": "2019-05-03","ownerId": 25748,"numAdult": 2}
三宗罪：错误处理此API中的错误处理是通过以下方式实现的：即使发生错误，所有请求也会返回200的响应代码。这意味着除了解析正文并检查是否存在error或errorCode字段之外，没有其他方法可以区分响应是成功还是失败。该API仅包含6个错误代码，如下所示：

文章插图
Error codes of Beds24 API
请考虑在出现问题时不要使用这种返回响应代码200（成功）的方法，除非这是在API框架中使用的标准方法。优良作法是使用大多数客户端和开发人员都可以识别的标准HTTP错误代码。例如，以上屏幕快照中的错误代码1009应该替换为401（未经授权）HTTP代码。如果API客户端可以预先知道是否解析主体以及如何解析主体（作为数据对象或错误对象），则将使工作变得更轻松。如果错误是特定于应用程序的，则最好在响应正文中返回400（错误请求）或500（服务器错误）以及相应的错误消息。
【API设计的七宗罪】对于给定的API选择哪种错误处理策略，只要确保它是一致的并符合广泛采用的HTTP标准即可。这将使我们的生活更轻松。
四宗罪："准则"以下是文档中API使用的"准则"：
使用API时请遵守以下准则

1.呼叫应设计为仅发送和接收所需的最少数据。
2.一次仅允许一个API调用，您必须等待第一个调用完成才能开始下一个API调用。
3.多个呼叫之间的间隔应间隔几秒钟。
4. API调用应尽量少用，并保持在合理的业务使用所需的最低限度内。
5. 5分钟内过度使用将导致您的帐户被封锁，而不会发出警告。
6.我们保留自行决定禁用任何我们认为过度使用API函数的访问的权利，恕不另行通知。

虽然第1点，第4点有意义，但我不同意其他观点。让我解释一下原因。
2.如果您正在构建REST API，则应假定该API是无状态的，在任何时间点都不应存在任何状态。这是REST在云应用程序中有用的原因之一。如果发生故障，可以自由地重新部署无状态组件，并且它们可以根据负载变化进行扩展。请确保在设计RESTful API时，它实际上是无状态的，并且开发人员无需关心"一次请求"之类的事情。
3.这是一个模棱两可，非常奇怪的准则。不幸的是，我无法弄清楚作者创建此"指南"的原因，但是它给人一种感觉，即在请求本身之外进行了一些处理，因此，紧接彼此进行调用可能会使系统处于某种错误状态。同样，作者说"几秒钟"的事实并没有提供有关两次请求之间实际时间的具体信息。
再次参见图5和6 。在这种情况下，没有解释什么是"过度" 。是每秒10个请求还是1个？此外，某些网站将拥有大量流量，并且仅由于这些原因而阻止它们使用API，而不会发出任何警告，可能会使开发人员远离此类系统。请在制定此类指南时具体说明，并在提出此类规则时考虑用户。
五宗罪：文件API文档的外观如下所示：

文章插图
Beds24 API documentation look&feel
这里唯一的问题是可读性和整体感觉。如果作者使用markdown而不是自定义非样式html，则同一文档的外观可能会更好。为了这篇文章的缘故，我在Dilliger的帮助下不到2分钟创建了一个更好的版本。结果如下：

文章插图
Styled version of the documentation
请使用工具创建API文档。对于简单的文档，上面的一个markdown文件就足够了，而对于更大，功能更丰富的文档，最好使用Swagger或Apiary之类的工具。
这是Beds24 API文档的链接，适合那些想要自己看一下的人。
六宗罪：安全API文档规定了关于所有端点的以下内容：
要使用这些功能，必须在菜单设置>>帐户>>帐户访问中允许API访问。
但是，实际上，任何人都可以请求获取数据，而无需为某些调用传递任何凭据，例如获取特定属性的可用性。在文档的不同部分中对此进行了说明：