API 设计最佳实践

对于致力于完善其 API 策略的团队来说，优秀的 API 设计是一个经常出现的话题。在之前的一篇博客文章中，我简要讨论了 API 设计的重要性。精心设计的 API 的好处包括：改善开发者体验、加快文档编制和提高 API 的采用率。但是，究竟什么是优秀的 API 设计？在这篇博客文章中，我将详细介绍设计 RESTful API 的一些最佳实践。

精心设计的 API 的特点

总的来说，有效的 API 设计应具备以下特点：

易于阅读和使用：精心设计的 API 易于使用，其资源和相关操作可被经常使用的开发者迅速记住。
难以误用：实现和集成设计良好的 API 将是一个简单的过程，且编写错误代码的可能性较小。它提供信息丰富的反馈，并且不对 API 的最终消费者强制执行严格的指导方针。
完整且简洁：最后，一个完整的 API 将使开发者能够针对您暴露的数据构建功能完善的应用程序。完整性通常是随着时间的推移而实现的，大多数 API 设计师和开发者都是在现有 API 的基础上逐步构建的。这是每个拥有 API 的工程师或公司都必须努力实现的目标。

为了说明下面列出的概念，我将以一个照片分享应用程序为例。该应用程序允许用户上传照片，并用拍摄照片的地点和描述相关情感的标签来描述它们。

集合、资源及其 URL

理解资源和集合

资源是 REST 概念的基础。资源是重要到足以自身被引用的对象。资源包含数据、与其他资源的关系，以及对其操作的方法，以允许访问和操作相关信息。一组资源称为集合。集合和资源的内容取决于您的组织和消费者需求。例如，如果您认为市场将从获取产品用户群的基本信息中受益，那么您可以将其公开为集合或资源。统一资源定位符 (URL) 标识资源的在线位置。此 URL 指向您的 API 资源所在的位置。基本 URL 是此位置的固定部分。对于照片分享应用程序，我们可以通过集合和资源来公开有关使用该应用程序的用户的数据，并通过适当的 URL 访问。

/users: 用户集合
/users/username1: 包含特定用户信息的资源

名词更好地描述 URL

基本 URL 应该整洁、优雅、简单，以便使用您产品的开发者可以轻松地在他们的 Web 应用程序中使用它们。冗长且难以阅读的基本 URL 不仅看起来糟糕，而且在尝试重新编码时也容易出错。名词应始终被信任。关于资源名词是使用单数还是复数没有规定，但建议集合使用复数。在所有资源和集合中保持相同的复数形式以保持一致性是一个好习惯。保持这些名词不言自明有助于开发者从 URL 中理解所描述的资源类型，这最终使他们在使用您的 API 时能够自给自足。回到照片分享应用程序，假设它有一个公共 API，其中 /users 和 /photos 是集合。请注意它们都是复数名词吗？它们也都是不言自明的，我们可以推断 /users 和 /photos 分别提供关于产品注册用户群和共享照片的信息。

使用 HTTP 方法描述资源功能

所有资源都有一组可以对其进行操作的方法，以处理 API 暴露的数据。 RESTful API 主要由 HTTP 方法组成，这些方法对任何资源都有明确定义和独特的动作。以下是常用 HTTP 方法的列表，它们定义了 RESTful API 中任何资源或集合的 CRUD 操作。

方法	描述
GET	用于检索资源的表示。
POST	用于创建新的资源和子资源
PUT	用于更新现有资源
PATCH	用于更新现有资源
DELETE	用于删除现有资源

（如果您想了解 PUT 和 PATCH 之间的区别，请查看 StackOverflow 上的此讨论。）将动词从您的 URL 中移除也是一个好主意。GET、PUT、POST 和 DELETE 操作已经用于操作由 URL 描述的资源，因此在 URL 中使用动词而不是名词可能会使您的资源操作变得混乱。在照片分享应用程序中，以 /users 和 /photos 作为端点，API 的最终消费者可以直观地使用上面描述的 RESTful CRUD 操作轻松地操作它们。

响应

提供反馈以帮助开发者成功

向开发者提供关于他们如何良好使用您产品的反馈，对于提高采用率和留存率大有裨益。每个客户端请求和服务器端响应都是一个消息，在理想的 RESTful 生态系统中，这些消息必须是自描述的。良好的反馈包括对正确实现的积极验证，以及对不正确实现的信息性错误，这些错误可以帮助用户调试和纠正他们使用产品的方式。对于 API，错误是提供使用 API 上下文的好方法。将您的错误与标准 HTTP 代码对齐。不正确的客户端调用应关联 400 类型错误。如果存在任何服务器端错误，则必须关联适当的 500 响应。对您的资源成功使用的方法应返回 200 类型响应。有许多响应代码。有关更多信息，请查看此 REST API 教程。一般来说，使用您的 API 时有三种可能的结果：-

客户端应用程序行为错误（客户端错误 - 4xx 响应代码）
API 行为错误（服务器错误 - 5xx 响应代码）
客户端和 API 正常工作（成功 - 2xx 响应代码）

每当最终消费者在使用您的 API 时遇到障碍时，引导他们走向成功将大大改善开发者体验并防止 API 误用。详细描述这些错误响应，但要保持它们简洁明了。在错误代码中提供足够的信息，以便最终用户可以开始修复原因，如果您觉得需要更多信息，请提供指向额外文档的链接。

为所有 GET 响应提供示例

精心设计的 API 还会提供成功调用 URL 后预期响应的示例。此示例响应应简单、明了、易于理解。一个好的经验法则是帮助开发者在五秒钟内准确理解成功响应会给他们什么。回到我们的照片分享应用程序，我们已经定义了 /users 和 /photos URL。/users 集合将以数组形式提供所有已注册用户的用户名和注册日期。您可以使用 API 设计工具，按照以下方式在 Swagger (OpenAPI) 规范中定义您的 API：

responses:
200:
description: 成功返回用户信息
schema:
type: array
items:
type: object
properties:
username:
type: "string"
example: "kesh92"
created_time:
type: "dateTime"
example: "2010-01-12T05:23:19+0000"

请注意数据类型和每个响应项中描述的示例，这是最终用户可以从成功的 GET 调用中预期得到的。最终用户将收到的成功 JSON 响应如下所示。

{
“data”:[
{
“Username”:“example_user1”,
“created_time":“2013-12-23T05:51:14+0000 ”
},
{
“username”:“example_user2”,
“created_time":“2015-3-19T17:51:15+0000 ”
}
....
]
}

如果最终用户成功使用 GET 方法调用端点，用户应获取上述数据以及 200 响应代码以验证正确的使用。同样，不正确的调用应生成适当的 400 或 500 响应代码，并附带相关信息以帮助用户更好地操作该集合。

请求

优雅地处理复杂性

您尝试暴露的数据可以通过许多属性来表征，这些属性可能对使用您的 API 的最终消费者有益。这些属性描述了基本资源，并分离出可以使用适当方法操作的特定信息资产。 API 应该努力实现完整性，并提供所有必需的信息、数据和资源，以帮助开发者无缝集成。但完整性意味着要考虑 API 的常见用例。可能存在无数这样的关系和属性，为每个属性定义资源并不是一个好的做法。资源暴露的数据量也应考虑在内。如果您试图暴露大量数据，可能会对服务器产生负面影响，尤其是在负载和性能方面。上述情况和关系是 API 设计中的重要考虑因素，可以使用适当的参数来处理。您可以在查询参数中的“?”后面隐藏属性并限制响应，或者使用路径参数隔离客户端正在处理的数据的特定组件。让我们以照片分享应用程序为例。对于开发者来说，获取特定位置和特定标签下共享的所有照片的信息可能很有用。您还希望将每个 API 调用的结果数量限制为 10，以防止服务器负载。如果最终用户想查找波士顿所有带 #winter 标签的照片，调用将是：

GET /photos?location=boston&hashtag=winter&limit=10

请注意，复杂性现在已简化为与查询参数的简单关联。如果您想根据客户端的请求提供特定用户的信息，调用将是：

GET /users/kesh92

其中 kesh92 是用户集合中特定用户的用户名，将返回 kesh92 的位置和注册日期。这些只是您可以设计参数以实现 API 完整性并帮助您的最终开发者直观地使用您的 API 的一些方法。最后，当有疑问时，请将其搁置。如果您对特定资源或集合的功能有疑虑，请将其留到下一个迭代。开发和维护 API 是一个持续的过程，等待来自正确用户的反馈对于构建一个强大的 API 来说大有裨益，它能让用户以创造性的方式集成和开发应用程序。

开始 API 设计

没有一种 API 设计方法适用于所有组织。上述建议仅是建议和推荐，可根据您的用例和需求采用或舍弃。 API 设计至关重要的主要原因之一是帮助最终消费者使用您的 API。他们的需求应该是设计和构建优秀 API 的指路明灯。

有兴趣开始 REST API 的设计吗？了解 Swagger API 设计工具如何提供帮助。