Web应用程序的API设计原则

API设计原则：构建开发者喜爱的API

一个设计良好的API使用起来是一种享受。它可预测、一致，并且能按照开发者的预期工作。无论你是在构建REST API、GraphQL API还是其他类型的API，遵循良好的设计原则都能让你的API更易于学习、使用和集成。

一致性是关键

API设计最重要的原则是一致性。在整个API中使用相同的命名约定——要么使用camelCase，要么使用snake_case，但不要混用。为每个端点使用相同的错误格式。在所有地方使用相同的分页方法。使用过API某一部分的开发者应该能够猜测另一部分是如何工作的。

一致性也适用于端点的行为。如果POST请求创建一个资源，那么所有POST请求都应该创建资源。如果DELETE请求返回204 No Content，那么所有DELETE请求都应该返回204。可预测的行为使你的API直观易懂。

为客户端设计，而不是为数据库设计

人们很容易围绕数据库表来设计API端点。但你的API应该服务于客户端的需求，而不是反映你的数据库模式。思考客户端需要什么数据以及他们希望如何访问这些数据。如果移动应用需要用户的个人资料和最近的订单，那么提供一个端点，在一次响应中同时返回这两者，即使它们来自不同的表。

这可能意味着创建聚合来自多个来源的数据的端点。这没问题——API应该让客户端的工作更轻松，而不是更困难。

优雅地处理错误

错误是不可避免的。一个好的API能让错误易于理解和处理。使用结构清晰、一致的错误响应。包含一个客户端可以编程解析的错误代码、一条人类可读的消息以及关于出错原因的详细信息。对于验证错误，指出哪个字段无效以及原因。

正确使用HTTP状态码。不要在响应体中返回200并附带错误消息——对于错误请求使用400，对于身份验证失败使用401，对于授权失败使用403，对于未找到使用404，对于服务器错误使用500。状态码一目了然地告诉客户端发生了什么。

对API进行版本控制

你的API会发生变化。版本控制让你可以在不破坏现有客户端的情况下进行更改。最简单的方法是在URL中包含版本号：/api/v1/users、/api/v2/users。当你需要进行破坏性更改时，创建一个新版本，并给客户端时间进行迁移。

以明确的时间线弃用旧版本。在来自已弃用版本的响应中包含Sunset标头以警告开发者。只有在弃用期过后才删除旧版本。

彻底地文档化

一个设计良好的API是有文档的。OpenAPI规范（以前称为Swagger）是记录REST API的标准。它提供了API的机器可读描述，可用于生成交互式文档、客户端库和测试套件。良好的文档包括示例、描述错误响应，并解释每个端点的业务上下文。