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 for User by Admission Code，发送通知到用户的邮箱和这个{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

我的问题是“reset_password”...我认为由于正确的设计原则，任何动词都不应该在 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"}

等等……