REST API端点 - 奇怪的路径参数

Question

我正在学习REST API和URI设计，我在这里找到了一个：

https://raw.githubusercontent.com/JeanVEGA/MI-MPR-DIP-Admission/master/examples/requests.sh

我有几个问题。

例如：

User.resetPassword，由用户{email}

匿名

curl -i -X POST http://localhost:9090/admission/services/user/person/email:{email}/reset_password

我不了解建筑email:{email} ......这是什么意思？这意味着如果我有String path param，我需要这样做吗？

类似的是：

Term.get

curl -i -H "Accept: application/json" -H "X-CTU-FIT-Admission-Session: [session identifier from User.identity]" http://localhost:9090/admission/services/term/dateOfTerm:{dateOfTerm}/room:{room}

room:{room} - 这是因为房间应该是123ABC吗？所以它不是一个数字所以需要以这种方式编写？

我的上一个问题：

用户按入学代码的User.resetPassword，向用户的电子邮件发送通知，此{email}

curl -i -H "X-CTU-FIT-Admission-Session: [session identifier from User.identity]" -X POST http://localhost:9090/admission/services/user/admission/{admissionCode}/person/email:{email}/reset_password

我的问题是＆＃34; reset_password＆＃34; ...我认为由于正确的设计原则，URI中没有动词...因为如果动词在URI中，我认为这意味着资源实际上是一个操作。

Answer 1

该url只能是资源标识符。所以这是一个url template，它等待一个唯一的电子邮件地址作为参数。填写的模板应如下所示：

./person/email:my@email.adr/reset_password

注意：的

reset_password不是有效的REST资源（它描述的是服务而不是资源），POST方法是mostly for resource creation（不是用于更新或部分更新）。真正的REST请求如下所示：

PUT ./person/email:{email}/password "newpass"
PUT ./person/{id}/password "newpass"
PUT ./person/email:{email}/identification_factors/password "newpass"
PATCH ./person/email:{email}/identification_factors {password: "newpass"}

依旧......