從REST API創建者和使用者的角度來看,什麼是REST API?

API代表應用程式介面(Application Programming Interface),是一個涵蓋許多不同事物的總稱。

我們已經看到瀏覽器如何提供一些API,以可用於我們的函式的形式。

我們已經看到Node.js如何通過其預設模塊為我們提供編程API。

API還表示另一種東西:創建通過可以被多個客戶端訪問的服務,並提供一些特定功能的服務。

廣義而言,我們目前有2類API:REST API和GraphQL API。

還有其他類型的API範式存在,例如SOAP,但它們在JavaScript世界中並不常見。

在本文中,我們將談論REST API。

端點

在REST API中,我們創建了客戶端可以訪問的多個端點。

假設我們想要公開一個人員列表。我們可以創建一個將響應於/people路徑的端點。

如果我們的服務監聽在test.com域上,我們將有test.com/people的URL。

該端點可以提供任何格式的數據,但通常我們使用JSON,這是一種方便的文本格式,用於在兩個服務之間通信數據。

/people端點可以提供一個人的名字列表,以及每個人的id。這可能是我們用來儲存它們在數據庫中的id

我們的系統還可以公開另一個我們稱之為/person的端點。它接受唯一標識一個人的id,類似於/person/1的形式。

我們的API將提供有關該人的更多信息,例如年齡、電子郵件和地址。

請注意,在第一個端點中我們沒有任何參數,但這一次我們有一個參數。

參數可以以不同的方式發送,並且並不是所有的端點都用於從服務器發送信息。我們很快就會看到一些其他的端點將用於執行操作。

方法

我提到了/people端點將返回我們系統中的人員列表。

這只是一個簡化,現在是時候進一步研究了。

REST API使用HTTP協議的原則來提供基於使用的HTTP方法的不同功能:GETPOSTPUTDELETE

GET是最常用的方法。當客戶端使用GET方法調用我們的API端點時,它表示它希望讀取數據。

GET /people將返回人員列表。

GET /person/1將返回一個人的詳細信息。

當HTTP方法為POST時,意義完全不同。端點將是相同的,但所需的操作將是另一個。

我們作為API構建者可以定義含義是什麼。

例如,我們可以創建一個POST /person端點,當被調用時會在數據庫中創建一個新的人。

它接收來自客戶端的數據,以我們可以選擇的預定義格式。我們很快將通過使用Express來看一個示例。

GETPOST是主要使用的2個方法。

有時我們使用PUTDELETEPUT有時用於更新資源,例如更改個人的地址。DELETE用於刪除一個資源。

在其他時候,POST用於除讀取之外的所有操作,其中使用GET

在這個選擇中我們有自由。

在資源中,我們指的是一個實體,例如在/people的復數形式中的人員,或在/person的單數形式中的一個人。

命名API端點

看看上面我使用的/people/person

這些都是名詞。

使用名詞作為端點的名稱,並使用HTTP方法表示動作,被認為是最佳做法。

更新一個人使用POST請求到/person端點。

如果你想創建一個API來發送消息給一個人,你將使用POST請求,使用/message端點,並通過它傳遞數據來識別要發送的人和消息。

一個REST API是無狀態的

REST API是無狀態的。

這意味著它在不同請求之間沒有記憶。

你可以找到大多數API實現一個API密鑰機制,作為追蹤誰在調用API的一種方式,並提供一種監控使用情況並強制限制的方法。

API也可以使用登錄/密碼機制進行保護。在這種情況下,API身份驗證過程將需要考慮到握手過程,以提供一個令牌,然後需要在每個未來的請求中發送它,以識別用戶和正確的授權。

回應

API調用會以兩種形式將回應返回給用戶:HTTP回應狀態碼和HTTP回應正文。

每個HTTP請求都有一個狀態碼。

對於HTTP回應狀態碼,我們有一些慣例:當你使用瀏覽器打開一個網頁時,網頁將返回一個200 OK狀態碼。如果找不到該頁面,則返回404 NOT FOUND狀態碼。

對於我們的API也是如此。

常見的狀態碼有:

  • 200 OK:這是成功的標準 HTTP 請求的標準回應。
  • 201 Created:通常是 POST 請求的回應。請求已完成,並建立了一個新的資源。
  • 400 Bad Request:由於用戶端引起的請求錯誤,服務器無法處理請求。錯誤可以包括錯誤的請求格式、過大無法處理等。
  • 401 Unauthorized:需要身份驗證並且客戶端未經授權。
  • 403 Forbidden:由於各種原因,該資源不可用。如果原因是對身份驗證,請使用401 Unauthorized狀態碼。
  • 404 Not Found:找不到所請求的資源。
  • 405 Method Not Allowed:該資源不能使用該HTTP方法訪問,但可能可以使用其他方法訪問。
  • 500 Internal Server Error:一個通用的啟示服器錯誤消息,當遇到意外情況並且沒有更具體的消息時給出。

你可以在HTTP狀態碼列表中找到完整的列表。值得注意的是,當你創建一個API時,應該始終返回正確的狀態碼,以通知你的用戶。

回應正文通常是一個JSON響應,其中包含了所請求的數據或錯誤消息。

消息的詳細內容由你,API構建者,或由構建API的人決定。