如何为设计计算器服务建模RESTAPI

Question

我一直在阅读有关为将向客户公开的REST服务设计API的最佳实践。例如，我们应该使用名词来命名所有公开的URI。此外，动词应遵循HTTP命令的语义。例如，GET请求不应该修改资源，而应该在这里使用PUT请求。我在一次采访中被问到这个问题，但我不能满意地回答这个问题——我正在设计一个计算器，它提供以下功能：对两个操作数进行加法、乘法、除法和减法。如何按照REST原则向客户端公开这些方法。这些操作要使用什么URI？我不确定是否将add操作映射到GET、PUT或POST。其他操作（除法、乘法等）相同。这里的指导方针是什么？

Answer 1

其他比我经验丰富得多的人则以好的方式回答了这个问题。

我只想指出这是一个非常好的问题。我正在读加州大学欧文分校的理查德·泰勒和其他人的论文。当菲尔丁在他的博士论文中描述REST时，理查德·泰勒是罗伊菲尔丁的顾问。在比较REST和SOAP的讨论中，本文包括了以下内容:

"...服务语义越接近内容语义，服务就越有可能拥有丰富的 REST API。

...

REST和SOAP之间的划分可能反映了缺乏设计指导;不以内容为中心的服务如何才能，例如拍卖竞标...以 REST 一致的方式干净地构造？

当他们说“更接近内容”时，他们的意思是服务看起来更像是最终用户要检索的一些动态或静态信息，而不是服务看起来像是主动为用户执行某些功能或计算的东西。

他们继续对此提供额外的指导——但是我还没有读完这篇论文，所以我会让你自己去查。：-）

在网络上搜索：从表示到计算：网络架构的演变，Richard N. Taylor，UCI

Answer 2

我认为REST这个术语的一个问题是它对不同的人可能有不同的含义。面试官可能对REST有不同的理解。当出现这样的事情时，我的第一个倾向是试图弄清楚REST对他们意味着什么。他们是指超媒体吗？他们关心你提到的动词和名词被正确使用吗？或者在他们看来，REST只是一些返回JSON的HTTPendpoint。所有这些都是可能的。

我倾向于回答以下问题：

GET /add/1/2
GET /multiply/5/6
etc..

Answer 3

这里的指导方针是什么？

你会怎么做一个网站？

每当有人问你关于 REST 的问题时，这应该是你的第一次启发式方法。REST 是一种
架构风格，专为“跨越多个组织的长期存在的基于网络的应用程序”而设计。这种体系结构样式的参考应用程序是万维网。

我正在设计一个计算器，它提供以下功能：在两个操作数上加、乘、除、减。如何按照REST原则向客户端公开这些方法。

客户端有三条信息，需要将其传达给服务器 - 操作和两个操作数。在网络中，收集此类信息的常用方法是提供表单。在这种情况下，它可能是操作的下拉列表，以及几个用于接受数字的文本控件。因为纯函数是安全的，所以我们可能会使用GET作为形式方法。因此，HTML 处理规则将采用表单描述的值，并将它们转录为查询部分中的键值对。

所以url看起来会像这样

<代码>/22520c7f-6207-490e-99c9-bd1bb37f4056？ op=添加

关键的概括是实现HTML表单扮演URI模板的角色-服务器将模板传递给客户机，客户机填写详细信息并将结果用作请求的目标。

这意味着，如果要将 HTML 替换为其他媒体类型，则需要指定 URI 模板的描述、描述可接受范围的某种机制以及哪些值可能是合理的默认值。

用于这些操作的 URI？

使用REST？绝对没关系。这是重点的一部分——客户端将URI视为不透明的值。

URI只是标识符；你可以把它们想象成程序中的变量名。机器不关心拼写是什么(只要这些拼写符合RFC 3986)。

由于拼写无关紧要，因此您可以使用任何碰巧的本地拼写约定。很多人喜欢“可破解”的URI - 标识符的拼写向人类读者传达了有用的信息。

URI是资源的标识符；“任何可以命名的信息都可以是资源”。这激发了一些“名词而非动词”的噪音——资源是网页、文档、图像、脚本或者...“资源”概念故意模糊，以便灵活运用。

我不确定是将add操作映射到GET、PUT还是POST。

关键是查看客户端请求的语义学。任何时候你所做的都是查询/查找，机器可以自动为用户做的事情，那么你正在查看安全语义学，方法很可能是GET或HEAD（特殊情况）。

如果我们要求服务器改变它自己的资源的表示，那么< code>PUT和< code>POST开始起作用。

在这种情况下，所有这些操作只是进行查找，因此< code>GET是合适的。

（值得注意的一点是，这些操作都不依赖于服务器状态；它们是纯函数。因此，使用按需编码——javascript或一些合理的替代品——为客户机提供服务，并使用客户机的处理器执行计算，而不是在网络上进行一系列往返可能是有意义的）。