我希望在现有项目上公开一些领域RESTful API。我需要建模的实体之一是一个单一文档:设置。设置是与应用程序一起创建的单例文档。我想通过设计良好的基于资源的RESTful API来公开它。
通常情况下,当为具有许多项目的资源建模API时,它是这样的:
选项1:如果我以同样的方式建模设置,那么以下API将被构建:
这对我来说有一些微妙之处:
这个设计方案消除了下面提到的细微差别,并且在执行PUT或PATCH时不需要id。我认为这是最一致的方法,因为所有请求都有相同的形式。
选项3:另一种选择是将id重新加入到PUT和PATCH中,要求其进行更新,但是API用户必须执行GET来获取单例的id。
这似乎不一致,因为GET 1请求的形状与UPDATE 1请求不同。它也不要求消费者执行GET以查找单例的标识符。
通常情况下,当为具有许多项目的资源建模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}/
这对我来说有一些微妙之处:
- 当只能存在一个项目时,我们返回一个数组。设置是应用程序创建的单例。
- 我们需要知道ID才能发出仅返回一个项目的请求
- 我们需要单例的ID才能进行PUT或PATCH操作
选项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,然后在更新请求中使用它的强烈理由,例如出于安全原因等?