REST不是一項技術,而是一種設計風格。它的核心思想是實現一種清晰明確的語義,用來描述Web操作。包含兩個主要因素:HTTP動詞和資源地址。

HTTP動詞的使用原則

參與Web操作的HTTP動詞主要有GET、POST、DELETE、PUT、HEAD、PATCH。實際上,幾乎所有的操作只需GET和POST就可以實現,為什麼還要有其它幾種呢?目的就是為了實現清晰明確的語義:DELETE /api/v1/post/18肯定比GET /api/v1/post?id=18&action=delete更清楚。

因此HTTP動詞使用的重點在於明確語義。例如更新操作,很多文章會說創建資源用POST、修改用PUT,實際上是對REST風格理解不透徹。

總體上,HTTP動詞分為兩類:冪等和非冪等。冪等是個數學概念,對於一元操作,如果它作用於任一元素兩次以上後所得的結果和第一次相同,就認為它是冪等的。簡單地說,如果一個接口,傳遞同樣的實參,多次請求的結果和一次沒有不同,就認為它是安全的、冪等的,反之,就是不安全、非冪等的。

GET、DELETE、PUT、HEAD是冪等操作,POST和PATCH是非冪等操作。因此,修改操作用POST還是PUT,要看操作本身的冪等與否。舉個例子,對於修改用戶描述的接口,調用任意次得到的結果都是相同的,所以它是冪等的,應該用PUT。而對於修改用戶登錄積分的操作,假設每次登錄加十分,重復調用會導致分數重復增加,這就是不安全、非冪等的,應該用POST。

資源地址的命名原則

資源地址是對被操作資源位置的描述,因此應該有以下幾個原則:

  • 全部使用名詞
  • 不使用駝峰風格
  • 資源名稱統一使用複數

對於前兩個,因為對資源的操作已由HTTP動詞表述,資源地址里不應該存在動詞,否則會造成語義的混亂。此外,不存在動詞也就不需要使用駝峰風格。例如,GET /api/v1/getUser/89,「get」在語義上就重復了。

關於資源名稱用複數的原則,主要是為了API在風格上的統一,同一種資源用同一個單詞表示,單、複數用資源的id表示,URI里有id的就是單數,否則是複數。

結論

REST是風格而不是技術,出bug的可能性不大,並不是能實現業務邏輯、沒有bug就是好代碼。風格錯了,連REST都不算。