标签：指南 HTTP api API products 使用 Restful 资源
作为软件开发人员，我们大多数人在日常生活中使用或构建 REST api。API 是系统之间的默认通信方式。亚马逊是如何有效地使用 api 进行通信的最佳例子。
在这篇文章中，我将讨论如何更好地设计 RESTful api 以避免常见错误。
Jeff Bezos’ (成功的关键) 的指令
你们中的一些人可能已经知道Jeff Bezos对亚马逊开发者的授权。如果你没听过，以下几点是它的关键。
- 因此，所有团队都将通过服务接口公开他们的数据和功能。
- 团队之间必须通过这些接口进行沟通。
- 不允许有其他形式的进程间通信，不允许直接链接，不允许直接读取另一个团队的数据存储，不允许共享内存模型，也不允许有后门。唯一允许的通信是通过网络上的服务接口调用。
- 他们使用什么技术并不重要。HTTP 、 Corba 、 Pubsub 、自定义协议都不重要。Bezos不在乎。
- 毫无例外，所有服务接口都必须从头开始设计，才能外部化。也就是说，团队必须进行规划和设计，以便能够向外部世界的开发人员公开接口。没有例外。
- 任何不这样做的人都会被解雇。
最终，这被证明是亚马逊成功的关键。亚马逊可以构建可扩展的系统，之后还可以提供像亚马逊网络服务这样的服务。
RESTful api 的设计原则
现在，让我们来了解在设计 RESTful api 时应该遵循的原则。
保持精简
我们需要确保 API 的基本 URL 是简单的。例如，如果我们想为产品设计 api，它应该是这样设计的:
/products
/products/12345
第一个 API 是获取所有产品，第二个 API 是获取特定产品。
用名词(nouns)而不是动词(verbs)
很多开发者都犯了这个错误。他们通常忘记了我们有 HTTP 方法来更好地描述 API，并最终使用 API url 中的动词。例如，获取所有产品的 API 应该是:
/products
而不是如下所示
/getAllProducts
到目前为止，我已经看到了一些常见的 URL 模式。
使用正确的 HTTP 方法
RESTful API 有各种方法来指示我们将使用此 API 执行的操作类型。
- GET — 获取资源，请求指定的页面信息，并返回实体主体。
- POST — 创建资源，向指定资源提交数据进行处理请求（例如提交表单或者上传文件）。数据被包含在请求体中。POST 请求可能会导致新的资源的建立和/或已有资源的修改。
- PUT/PATCH — 更新现有资源，用来对已知资源进行局部更新 。
- DELETE — 删除现有资源，请求服务器删除指定的页面。
我们需要确保在给定的操作中使用正确的 HTTP 方法。
使用复数
这个话题有点争议。有些人喜欢保留带有复数名称的资源 URL，而另一些人喜欢保留单数。例如-
/products
/product
我喜欢保持它的复数，因为它避免了我们谈论的是获取单个资源还是集合的混淆。它还避免了添加额外的东西，将所有内容附加到基本 URL,比如 /product/all,有些人可能不喜欢这样，但我唯一的建议是在整个项目中保持统一。
使用参数
有时候，我们需要一个 API，它应该比仅仅通过 id 来讲述更多的故事。在这里，我们应该利用查询参数来设计 API。
/products?name=’ABC’应该优先考虑/getProductsByName/products?type=’xyz’应该优先考虑/getProductsByType
这样，您就可以避免设计简单的长网址。
使用正确的 HTTP 代码
我们有很多 HTTP 代码。我们大多数人最终只使用了两种 200 和 500! 这当然不是一个好的做法。下面是一些常用的 HTTP 代码。
- 200 OK — 这是显示执行的操作成功的最常用的 HTTP 代码。
- 201 CREATED — 当您使用 POST 方法创建新资源时，可以使用此方法。
- 202 ACCEPTED —这可以用来确认发送给服务器的请求。
- 400 BAD REQUEST —当客户端输入验证失败时，可以使用此方法。
- 401 UNAUTHORIZED / 403 FORBIDDEN— 如果用户或系统无权执行某项操作，则可以使用此选项。
- 404 NOT FOUND— 如果您正在寻找某个资源，并且该资源在系统中不可用，则可以使用该资源。
- 500 INTERNAL SERVER ERROR — 这永远不应该被明确抛出，但是如果系统失败，可能会发生。
- 502 BAD GATEWAY — 如果服务器从上游服务器接收到无效响应，则可以使用此选项。
版本控制
Api 的版本控制非常重要。许多不同的公司以不同的方式使用版本。有些使用版本作为日期，有些使用版本作为查询参数。我通常喜欢在资源前面加上它。例如:
/v1/products
/v2/products
我也想避免使用 /v1.2/products, 这意味着 API 会经常变化。此外，在 url 中可能不容易看到点 (.)。所以保持精简。
保持向后兼容性总是一个很好的做法，这样如果你改变 API 版本，消费者就有足够的时间进入下一个版本。
使用分页
当您公开可能返回大量数据的 API 时，必须使用分页，如果没有进行适当的负载平衡，消费者可能最终会关闭服务。我们需要始终记住，API 设计应该是完整的证明和傻瓜证明。
这里建议使用 limit和 offset.例如:, /products?limit=25&offset=50. 还建议保留默认限制和默认偏移。
支持的格式
选择 API 的响应方式也很重要。大多数现代应用程序都应该返回 JSON 响应，除非你有一个仍然需要获得 XML 响应的遗留应用程序。
使用正确的错误信息
保持应用程序发送的一组错误消息并以正确的 id 对其做出响应总是一个很好的做法。例如，如果您使用 Facebook graph APIs，如果出现错误，它会返回如下消息:
{
"error": {
"message": "(#803) Some of the aliases you requested do not exist: products",
"type": "OAuthException",
"code": 803,
"fbtrace_id": "FOXX2AhLh80"
}
}
我还看到了一些例子，在这些例子中，人们返回带有错误消息的 URL，这告诉你更多关于错误消息的信息以及如何处理它。
OpenAPI 规范的使用
为了让你公司的所有团队遵守某些原则，使用 OpenAPI 规范是很有用的。OpenAPI 允许您首先设计 api，并以更简单的方式与消费者分享。
结论：
很明显，如果你想更好地交流，api 是一条路。但是如果它们设计得不好，可能会增加混乱。因此，尽最大努力做好设计，剩下的只是实现。
标签：指南,HTTP,api,API,products,使用,Restful,资源 来源： https://www.cnblogs.com/mouseleo/p/12003597.html
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。