如果我需要两个 GET，任务的 RESTFUL API 应该如何？答案

【问题标题】：How should RESTFUL API for tasks look like if I need two GETs?如果我需要两个 GET，任务的 RESTFUL API 应该如何？
【发布时间】：2019-04-14 16:51:05
【问题描述】：

我想为网站抓取服务设计一个 RESTful API。用户将任务委托给服务。每个任务都是一个必须转义的网站。用户可以检查任务的状态。完成任务后，用户可以获取任务结果。状态可以是“Waiting”、“In progress”或“Done”，完成后用户可以获得数据。

我现在拥有的是：

我还需要两个端点：一个用于获取任务状态，另一个用于从网站获取抓取的数据。 GET 应该是什么样子？

或许

但是那会返回/tasks/{id}/ 呢？

如果我还想以 html 的形式呈现已转换的数据怎么办？我应该使用

【问题讨论】：

这很主观，只要有意义，你就可以了。 /tasks/status/{id} 和 /tasks/results/{id} 怎么样？
也许GET /tasks/{id} 应该根据任务是否完成返回不同的状态？例如。 204 No Content until there's data, then 200 OK with the data?或者做这样的事情：farazdagi.com/2014/rest-and-long-running-jobs，用 202 Accepted 回复 POST，提供一个 Location 来轮询那里的工作状态，并最终返回 303 See Other 和数据的位置。跨度>
@FelDev 为什么/tasks/status/{id} 而不是/tasks/{id}/status 哪种方式更好？
状态是任务的属性，/tasks/{id}/status 会更有意义，如果这是你要去的方向。

【解决方案1】：

POST /tasks - post a URL to scrape
GET /tasks - returns a list of tasks

这很好。请注意，当您 POST 成功时，缓存失效会启动。通用客户端将知道先前返回的任务列表表示不再有效。

GET /tasks/{id} - return a status? Or return the data?

为什么不两者兼而有之？ /tasks/{id} 标识一个资源；您可以使用任何您喜欢的表示形式。表示没有理由不应该包含可选元素。

（Herustic：网页会是什么样子？你真的觉得这个概念需要两个不同的页面吗？如果不是，那么它可能是一个资源在您的 API 中。）

如果我还想以 html 的形式显示转义数据怎么办？

相同的标识符适用于多个表示；客户端可以使用Accept 标头向服务器描述其偏好。

您可能想考虑一下客户端如何知道哪些表示是可能的问题。在网络上，HTML 规范描述了许多不同类型的链接——例如，当浏览器遇到脚本标签或图像标签时，它们可以声明不同的偏好。您需要在自己的媒体类型中使用类似的内容。

决定这些也应该是不同的资源没什么错。任何一种方法都可以以与 REST 架构风格一致的方式实现。

【讨论】：

【解决方案2】：

我真的不知道限制条件，但 GET /tasks/{id} 可以返回状态和数据（如果可用）。

如果您不想这样做（例如，如果从性能角度来看过于频繁地获取数据会成为一个问题），那么拥有以下选项似乎是明智的：

GET /tasks/{id} @returns status and other plain task fields

然后：

GET /tasks/{id}/scrappeddata @returns data

为什么？因为，这种方式可能最符合您的模型（和/或您的 API 用户心智模型）。

【讨论】：

但关键是状态是“进行中”或“完成”，所以当它完成时我返回数据，当它正在进行时我不能返回任何东西。所以调用GET /tasks/{id} 并接收“IN PROGRESS”或数据似乎在语义上是错误的
实际上，我考虑过类似的查询响应：{"status":"done","data":"random scrapped data"} 或 {"status":"in progress", “数据”：”” }。从任务的角度来看，这在语义上是正确的。

【解决方案3】：

在为 RESTFUL api 命名路由时没有硬性规定。您可以遵守约定、了解最佳实践、来自 SO 的建议，但归根结底，您是设计 API 的人，因此您比其他任何人都更清楚什么适合您的特定用例。

搜索“rest api命名最佳实践”或“如何构建rest api路由”，你会得到很多想法。

我和@jonrsharpe 提出的 2 条建议都是有效的，由您决定什么对您的项目有意义。

【讨论】：