4、API设计最佳实践指南

API设计最佳实践指南

1. 协议选择

在API设计中，协议的选择至关重要。虽然有适用于常用语言的库，但如果自定义协议更适合特定用例，那它可能是正确的选择。不过，通常REST基于HTTP协议，这是一个广为人知的协议，现代编程语言都支持它，也是整个互联网的基础，大多数开发者对其基本使用方法有一定了解。

需要注意的是，没有一种协议能完美适用于所有场景。在选择时，要考虑API的需求，并确保所选协议与REST兼容。

2. 易于记忆的访问点

客户端应用与API的接触点称为端点。API需要提供这些端点，以便客户端访问其功能，可通过所选的通信协议来实现。这些访问点的名称应具有助记功能，帮助开发者仅通过阅读就能理解其用途。

例如， GET /books/action1 是一个命名不佳的访问点示例，虽然引用了 books 实体，但动作名称不明确，未来含义可能改变，会导致现有客户端出现问题。而 GET /books 则遵循REST和相关标准，能让开发者清楚知道该请求会返回书籍列表，并且可以将此模式复制到其他资源。

3. 统一接口

统一接口在API设计中非常重要。在定义端点时，要保持一致性，包括端点名称、请求格式和响应格式。虽然响应格式可能有多个版本，但默认格式应保持一致。

以PHP编程语言为例，部分函数名使用下划线分隔，部分则不使用，这给开发者带来困扰，需要频繁查阅文档。在API设计中，若根据动作而非资源来命名端点，如 /getAllBooks 、 /submi