Categories
程式開發

請不要再管它們叫REST API了


2000年初,Douglas Crockford宣稱JavaScript是世界上被誤解得最深的一門編程語言。造成誤解的主要原因是糟糕的命名方式、設計上的錯誤和不嚴格的標準,等等。所以說,導致這種誤解是很自然的。

去年,我在推特上發了一條有關REST架構範式的推文。

請不要再管它們叫REST API了 1

大多數人認為基於URL和HTTP動詞設計的API就是REST API,但這樣的想法實際上錯得離譜。

這個誤解存在了很長一段時間。與JavaScript不一樣的是,REST指南已經說得很清楚了,REST這個名詞強調了狀態轉換(State Transfer),但大多數所謂的REST API設計者卻忽略了這一點。

如果你問一下身邊的程序員他們設計的API是否支持HATEOAS,他們十有八九會瞪大了眼睛看著你,然後說:你到底在說什麼?

然而,REST的名字本身就說明了一切。它並沒有說要使用哪一種協議,也沒有說使用哪一種方式來標識資源,它只說到表示性狀態轉移(REpresentational State Transfer)。 Roy Fielding博士說,狀態轉移管理是REST API的一個必要條件。

真正的REST API應該為客戶端提供狀態以及在狀態之間進行切換的方式。它提供了資源的表示(不一定是JSON格式)和指向相關資源的鏈接(超鏈接),這些鏈接可以讓應用程序從一個狀態切換到另一個狀態。如下例所示:

{
  "id": 463219,
  "firstName": "John",
  "lastName": "Smith",
  "company": "Acme Inc.",
  "salary": 72500,
  "links": [
    {
      "href": "https://api.myapp.com/employees/employee/463219",
      "rel": "self"
    },
    {
      "href": "https://api.myapp.com/companies/company/375",
      "rel": "company"
    },
    {
      "href": "https://api.myapp.com/payments/employee/463219",
      "rel": "payments"
    }
    ]
}

這個例子提供了資源的描述和其他相關資源的信息。

需要特別提到的是,是否使用HTTP協議並不重要。 REST的關鍵之處在於讓服務器端來負責客戶端的狀態轉移。客戶端的狀態幾乎是由服務器端來驅動的,所以,討論API版本管理並沒有多大意義。客戶端只要知道REST API的入口點就可以了,剩下的根據服務器端的響應來做決定,但這一點卻被大多數人忽略了。

只是簡單地將CRUD操作映射到HTTP動詞的API與應用程序狀態轉移絲毫扯不上關係,你可以把它們叫作Web API或HTTP API,但請不要把它們叫作REST API。

延展閱讀

我們為什麼從 REST 轉向 gRPC

英文原文

Please, Don’t Call Them RESTful