Restful風格api設計(HttpMethod)

文章目錄

• 寫操作
• 修改
• 禁用

這篇文章主要是讨論對于各種業務需求如何選擇 HttpMethod,一般來說HttpMethod的選擇應該和URL一起考慮,是以這裡也有涉及,但是主要是讨論HttpMethod

寫操作

對于某些記錄使用者操作的系統(特别是還提供了對操作記錄的檢視)而言,有些應該是讀的操作變成了寫操作,例如電商中的搜尋,也許有人說應該從這個操作的原意或者業務含義來考慮這個操作是否是寫,但是如何判斷原意又變成了見仁見智的問題,一般來說程式員之間很難在業務上達成一緻,我這裡提供一個更加精确的定義:如果一個接口的調用會導緻另一個原本能調用成功的接口的調用失敗,那麼這兩個接口都是寫操作,為什麼一定要失敗,而不是使用改變呢,因為寫操作很可能導緻改變.之前我想到的辦法是一個使用者的操作能否導緻另一個使用者能感覺到這個定義,但是感覺又變成了玄學,例如可以通過頁面檢視就是一例.

上面這個定義可以确定編輯和删除的情況,但是對于新增的情況有點無能為力,因為在POST之前,一些資源是不存在的,必然就不會有原本能調用成功的接口,如果反過來定義導緻原本調用失敗的接口調用成功呢?這樣看來應該也是寫操作,畢竟這改變了狀态機的狀态,但是這樣的是否是POST操作呢?

修改

這兩個接口都是修改操作,其最大的差別得救PUT是幂等的而PATCH不是,這樣看上去PATCH用于以下兩種情況比較合适

• 原字段是數組類型

  在這個數組上添加元素,這樣隻需要把新增的元素傳過來而無需考慮數組原有元素,對于删除操作一般是使用PUT把結果傳過來

• 原字段是數字類型

  這樣就出發了加法操作,如果想減少則傳過來負數即可

  問題是有的時候會指定結果和指定過程都存在,則難以選擇

禁用

這個主要用于禁用和删除的情況,特别是沒有删除的禁用情況.這裡的禁用一般是指除了在主維護頁面其他地方,一般是操作的下拉框等都不會出現,對于查詢的下拉框可能會出現.另外有的時候禁用狀态還可以再執行啟用操作.我們先跳過禁用看下啟用如何來操作,一般是這樣的URL:

POST /account/{id}

PUT /account/{id} -d {“isEnabled”:true}

對于PUT方案的缺點是會和其他操作的URL沖突,而POST方案則沒有這個問題.不過如果PUT對于不同業務采用了類SOAP的方案也可以為啟用指定專有的URL,例如

PUT /account/{id}/enable -d {“isEnabled”:true}

PUT /account/{id}/enable -d true

如果采用上面哪種方案,都可以解決URL征用的問題,但是這樣和業務上出現不一緻.特别是對于禁用操作有限制條件的情況.

如果采用了上面的POST方案,也有兩種細分

POST /account/{id}

POST /enabled-account/{id}

對于第二種似乎語義更明确,但是這種準确也帶來了複雜性暴露了出來,因為一般GET操作是如下格式的

GET /accounts

GET /account/{id}

而enabled-*格式的URL就與GET不一緻了,如果采用了這種方案就需要把GET的url同時做出變更

另外采用DELETE的一個問題是無法攜帶更多的資訊,當然,對于DELETE操作而言,如果這個記錄真的被删除了,那麼也就查不到了,也就不用攜帶資訊了.