系统设计 | RESTful API 使用问题和建议

文章讨论了RESTful API的局限性以及如何在实践中优化RESTful风格的API设计。RESTful API是基于HTTP协议的一种理想化网络服务设计，由Roy Fielding提出，但在实际应用中遇到了一些表达力不足的问题，如静态资源的抽象困难、HTTP Method和Status的扩展限制。

为了解决这些问题，作者提出了一些RESTful API设计的建议：

• 使用版本号：推荐使用URL前缀来实现API版本化，以降低对API定义的侵入性。
• 资源路径设计：建议使用领域模型来设计资源路径，如使用服务名、聚合根等，并在必要时添加属性或动作。
• HTTP Method选择：出于团队理解成本考虑，建议限制使用GET、POST、PUT和DELETE四种方法。
• 实体的单复数：通过URL路径应能识别返回结构类型，比如单个资源还是资源列表。
• 幂等性实现：GET本身具有幂等性，PUT和DELETE应设计为幂等的，POST可以根据需要设计幂等性。
• 查询语言设计：可以提前设计一套基于Query参数的查询规则，包含分页、排序、搜索和过滤等。
• 状态码选用：状态码用于前端处理通用错误，业务规则错误统一使用409状态码并返回标准错误信息。
• 批量处理：RESTful API设计中应明确批量处理的实现方式，比如通过增加/batch后缀或前缀。
• 动词名词化：在充分建模的情况下，某些动词API可以转换为名词化设计。
• 成功与错误的返回区分：2xx状态码返回成功对象，其他状态码返回错误对象，避免使用容器包装。
• 创建和更新的返回信息：权衡是否需要返回处理后的对象，以提高性能和简化开发。

文章最后建议参考一些成熟的API设计规范和示例，如GitHub REST API和JSON API等。