关于api:RESTful-API-设计最佳实践

良好的 API 设计是一个常常被提及的话题，特地是对于那些试图欠缺其 API 策略的团队来说。一个设计良好的 API 的益处包含：改良开发者体验、更疾速地编写文档以及更高效地推广你的 API。然而，到底什么才形成了良好 API 设计呢？在这篇博客文章中，我将具体介绍几个为 RESTful APIs 设计最佳实际。

一个设计良好的 API 的特点

一般来说，一个无效的 API 设计将具备以下特点：

易于浏览和应用： 设计良好的 API 将很容易应用，并且开发人员能够疾速记住其资源和相干操作。

难以误用： 实现和集成具备良好设计的 API 是一个简略间接的过程，并且缩小编写错误代码。它提供了信息反馈，并且不会对 API 最终用户强制执行严格指南。

残缺而简洁： 残缺的 API 将使开发人员可能针对您公开数据创立全面应用程序。通常状况下，实现须要工夫，大多数 API 设计师和开发人员在现有 API 上逐渐构建。这是每个领有 API 工程师或公司必须致力谋求的现实状态。

为了阐明上面列出的概念，我将以一个照片分享应用程序为例。该应用程序容许用户上传照片，并应用拍摄这些照片的地位和形容与之相关联情感的标签来对它们进行特色化。

汇合、资源及其 URL

了解资源和汇合

资源是 REST 概念的根底。一个资源是一个重要到足以被援用自身的对象。一个资源有数据，与其余资源的关系，以及操作它来容许拜访和操作相干信息的办法。一组资源称为汇合，汇合和资源内容取决于您的组织和消费者需要。例如，如果您认为市场将受害于获取无关产品用户群体的根本信息，则能够将其公开为汇合或资源。对立资源定位符（URL）标识了一个资源在线地位。这个 URL 指向 API 所在位置中资源存在处。根底 URL 是此地位的统一局部，在照片共享应用程序中，咱们能够通过适当的 URL 拜访通过汇合和资料库应用该应用程序用户数据。

1. /users: a collection of users
2. /users/username1: a resource with information about a specific user

更好地形容 URL

根本的 URL 应该整洁、优雅和简略，这样开发人员就能够在他们的 Web 应用程序中轻松应用它们。一个长而难以浏览的根本 URL 不仅看起来不好，而且在尝试从新编码时也容易出错。对于一致性，在所有资源和汇合上都放弃雷同数量是很好的做法。将这些名词自我解释有助于开发人员理解从 URL 形容的资源类型，最终能够使他们在应用 API 时变得更加独立自主。

回到照片共享应用程序，假如它有一个公共 API，并具备 /users 和 /photos 作为汇合，请留神它们都是复数名词，它们也是自我阐明性质并且咱们能够推断出 /users 和 /photos 别离提供对于产品注册用户群体和分享照片信息。\
用 HTTP 办法形容资源性能

所有资源都有一组能够对其进行操作的办法，以解决 API 公开的数据。RESTful API 次要由具备明确定义和独特操作的 HTTP 办法组成，这些办法定义了任何资源或汇合的 CRUD 操作。以下是罕用的 HTTP 办法列表，它们为 RESTful API 中任何资源或汇合定义了 CRUD 操作：

在 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 汇合将以数组模式提供已注册该应用程序的所有用户的用户名和退出日期。

  responses:
  200:
  description: Successfully returned information about users
  schema:
  type: array
  items:
  type: object
  properties:
  username:
  type: "string"
  example: "kesh92"
  created_time:
  type: "dateTime"
  example: "2020-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 的指路明灯。

Eolink 翻译，原文地址：https://swagger.io/resources/articles/best-practices-in-api-d…