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

我的問題是“ reset_password ” ...我認為，由於正確的設計原則，URI中不應包含任何動詞...因為如果謂詞處於URI中，我認為這實際上意味着資源是一種操作。

Answer 1

該URL只能是資源標識符。 因此，這是一個等待唯一電子郵件地址作為參數的url模板 。 填寫的模板應如下所示：

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

注意：

reset_password不是有效的REST資源（它描述的是服務而非資源），而POST方法主要用於創建資源 （不適用於更新或部分更新）。 實際的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"}

等等...