为什么 RESTful Web 服务设计可以帮你思考正确的事情 已翻译 100%

oschina 投递于 2018/09/10 15:53 (共 6 段, 翻译完成于 09-27)
阅读 1909
收藏 29
1
加载中

你可能管理一个API。或许你正准备做一个,并且很期待开始。但是要当心,因为好的API设计可能很难

设计一个好的API会有很多事情需要考虑。与设计web用户界面不同,您可能不了解所有客户端的用例。或许在不同平台有不同的客户端。如果你选择跟着自己的习惯做而不是根据现有的范例做时,这个困难会被放大。不要这么做。你会冒险花费大量的时间考虑不重要的事情和忽略重要的事情。

kevinlinkai
翻译于 2018/09/11 17:16
0

我喜爱 RESTful Web 服务或基于 HTTP 的 REST 的原因之一,就是它驱使我思考 API 的重要需求。我也不用花费太多时间来考虑那些无聊的惯例,比如,“我怎么告诉用户哪出现问题了?”,相反,我思考,“我怎么告诉用户他们的验证失败了?”,答:400 状态码。完成了。我之后会给出更多的例子,但首先,重要的是要记住,除了 RESTful Web 服务之外,还有更多其他的框架存在。

在我们深入讨论可以选择的框架时,你怎么知道要选择哪一个 API 设计框架?做出这决定可能很困难。为了让事情变的简单点,Phil Sturgeon 已经提出了一些很好的建议,在这里我会总结一下。其中提到了 3 个流行的框架:gRPC, 基于 HTTP 的 REST,以及 GraphQL。他们不是竞争对手,他们有不同的适用范围。

gRPC 对内部 API 或者与客户紧密相关的 API 非常适合。

当客户有非常相似的需求和工作流,还要能运行在不同平台的时候,基于 HTTP 的 REST 非常适合。

当带宽有限,而且你不确定客户需要什么的时候,GraphQL 更加适用。当你不需要特定服务器缓存和其他类似的协议的时候,它也值得一看。

在进行下一步之前,花点时间对可用资源作一些分析。

一旦你确定基于 HTTP 的 REST 是正确的选择时,我们看 RESTful Web 服务的一些方面,它们可以让你深入了解优秀的 API 设计。

琪花亿草
翻译于 2018/09/18 10:30
0

1. RESTful是资源丰富的

我很欣赏RESTful服务如何迫使我在资源方面进行思考。资源只是API中表示的内容。它不是数据库表,甚至不必是域模型的实体。它构成了整个API的框架。将你的API视为消费者可以操纵的一组资源。RESTful思维模式鼓励你思考真正重要的事项。

除此之外,只有一系列有限的方法可以对这些资源起作用:GET、POST、PUT、PATCH和DELETE。它还有一些其他用途,但这些是较大的。这并不意味着你的整个API将变为CRUD(Create, Read, Update, Delete,中译:增删改查)。 这意味着在关注其执行的操作之前,你将首先关注系统中的内容。

Tocy
翻译于 2018/09/12 09:28
0

2.形式高于功能

在采用HTTP服务时,采用已知模式(如JSON模式)也是有益的。基于restful的服务真正打开了一扇门,可以选择一个健壮的模式规范,它周围有很多工具。在向消费者展示数据方面,我发现这比我自己的系统要好得多。使用JSON模式这样的已知数据建模,消费者可以很容易地知道他们要返回的数据的形状。您还可以让他们知道是否需要请求字段。您的消费者甚至可以从中创建验证器。

3.RestFUL,不是REST

通常情况下,完全REST和使用超媒体并不常见。然而,使用RESTful服务可以帮助我考虑我的消费者将如何使用我的API。即使链接没有拼写出来,我也经常从入口点出发,通过连接的资源链来理解我的消费者可能如何使用我的API。这可以帮助我找到丢失的资源或没有意义的资源。

前端熬出来了
翻译于 2018/09/25 14:18
0

4.RESTful有助于填补这些空白

一旦我有了资源,我发现浏览一下主要的方法很有帮助:GET、POST、PUT、PATCH和DELETE。这让我看到资源是否为只读的。我可以编辑现有的还是只创建新的?也许资源足够大,需要通过补丁进行部分更新。消费者应该能够移除它吗?这些是我经常思考的问题。

5.想想那些不幸的道路

我发现查看HTTP状态代码对了解在资源操作上时会很有用。无法找到资源吗?我如何知道是消费者犯了错误(4xx)而不是服务器(5xx)?这个资源(409)可能存在并发问题吗?我把状态代码列表当作一个指南,引发诸如此类的问题,并引导我的思想走向一个健壮的API。

前端熬出来了
翻译于 2018/09/25 14:13
0

6.告诉世界怎么停止给你打电话

啊,缓存。你知道,当我阅读HTTP规范时,它让我大吃一惊,我意识到我们可以在客户端缓存,但让服务器告诉我们如何做。现在看来很明显,但这仍然很强大。在HTTP工作中自然会让我认识到我的资源有很多可以缓存,并让我专注于如何教消费者缓存它们。

你可以花很多时间来确定自己的习惯。您可以为诸如“我如何告诉我的消费者如何缓存”或“我如何告诉我的消费者他们犯了错误?”或者你可以屈服于老板的压力,“把事情做好”。但是如果你真的想要一个好的设计,看看RESTul web服务。如果这个范例符合您的需求,那么就让它来引导您的思维,让它为您的API提供健康的特性。解放你的思想,专注于真正重要的事情。RESTful web服务让您关注如何使您的API可用且简单。

前端熬出来了
翻译于 2018/09/25 13:28
0
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接。
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
加载中

评论(0)

返回顶部
顶部