rest - 如何为单个资源建模RESTful API？

Question

我希望在现有项目之上公开一些域RESTful API。我需要建模的实体之一只有一个文档:设置。设置是使用应用程序创建的，是一个单例文档。我想通过一个设计良好的基于​​资源的RESTful API来公开它。

通常，在为具有许多项目的资源建模API时，其内容类似于:

GET /employees/ <-- returns [] of 1-* items
GET /employees/{id}/ <-- returns 1 item
POST /employees/ <-- creates an item
PUT /employees/{id}/ <-- updates all fields on specific item
PATCH /employees/{id}/ <-- updates a subset of fields specified on an item
DELETE /employees/{id}/ <-- deletes a specific item

选项1:如果我以相同的方式对设置进行建模，则会构建以下API:

GET /settings/ <-- returns [] of 1-* items
[{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" }]

GET /settings/{id}/ <-- returns 1 item
{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" }

PUT /settings/{id}/
PATCH /settings/{id}/

这对我来说有一些细微差别:

当只有1个CAN和EVER WILL存在时，我们将返回一个数组。设置是应用程序创建的单例。

我们需要知道ID才能仅返回1项

来进行请求

我们需要单例的ID才能将其放置或修补

选项2:然后，我的想法朝这个方向发展:

GET /settings/ <-- returns 1 item
{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" }

PUT /settings/
PATCH /settings/

这种设计消除了下面带来的细微差别，并且不需要输入PUT或PATCH的ID。这对我来说是最一致的，因为所有请求都具有相同的形状。

选项3:另一种选择是将ID重新添加到PUT和PATCH中，以要求它进行更新，但是API用户必须执行GET才能获取单例的ID:

GET /settings/ <-- returns 1 item
{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" }

PUT /settings/{id}/
PATCH /settings/{id}/

这似乎不一致，因为GET 1的形状与UPDATE 1请求的形状不同。它还不需要使用者执行GET来查找单例的标识符。

有建模的首选方法吗？

在针对单例资源的RESTful API建模方面，有没有人有很好的引用资料？我目前倾向于OPTION 2，但我想知道是否有值得研究的好的资源或标准。

是否有令人信服的理由要求API使用者对资源的ID进行GET，然后在更新请求中使用它，也许出于安全原因等？

Answer 1

据我所知，选项2完全是RESTful的。

RESTful API的核心思想是您要操纵“资源”。 “资源”一词故意含糊不清，以便它可以指代对特定应用程序重要的任何内容，从而使API可以仅关注如何访问内容，而不管将访问什么内容。

如果您的资源是单例，则没有理由为其分配ID值。 ID非常有用，通常在RESTful API中使用，但是它们并不是使API成为RESTful的核心部分，并且，正如您已经注意到的那样，实际上会使访问单例资源更加麻烦。

因此，您应该删除ID，并同时拥有两个ID。

GET /settings/

和

GET /settings/{id}

始终返回设置单例对象。 (不需要通过ID进行访问，但是最好以防万一有人尝试它)。另外，请务必记录您的API终结点，以使使用者不要期望数组:)

回复:你的问题，

我相信选项2将是对此建模的首选方式，并且我相信要求您的消费者为id进行GET实际上会有点反模式。