17、深入理解API中的标准方法、部分更新与检索

深入理解API中的标准方法、部分更新与检索

1. 标准方法概述

标准方法是提升API一致性和可预测性的有力工具。所有标准方法都应遵循相同的行为原则，例如，所有标准创建方法的行为应该一致。

幂等性是指一个方法可以被重复调用，并且后续的每次调用都能得到相同的结果。不过，并非所有标准方法都必须具备幂等性，但它们不应产生副作用，即调用方法不应导致API系统的其他部分发生变化。值得注意的是，标准删除方法通常不应具有幂等性。

标准方法虽然对行为和特性的限制较为严格，但这也使得API更易于学习，用户可以利用他们对面向资源API的已有知识来使用这些API。

例如，我们可以思考以下问题：
- 一个标准的get方法同时更新访问计数器，它是否具有幂等性？
- 标准的delete方法是否具有幂等性？
- 为什么在标准列表方法中应避免包含结果计数或支持自定义排序？

2. 部分更新与检索的动机

在API设计中，部分更新和检索是非常重要的概念。以往我们通常将资源视为独立的原子单元，但在某些情况下，我们需要对资源进行更细粒度的操作。

2.1 部分检索

在大多数API中，检索资源时通常是全量获取或报错，即“全有或全无”。然而，当资源变得非常庞大，包含数百个不同的字段和子字段时，或者请求设备的计算资源有限（如小型物联网设备），又或者网络连接速度受限或成本高昂时，精确控制API返回的信息量就变得至关重要。

虽然单个新字段占用的空间可能很小，但在列出多个资源时，这些小空间会随着资源数量的增加而累积，最终可能变得相当可观。因此，为API用户提供仅检索他们真正感兴趣的