REST API介紹

從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方法的不同功能：GET，POST，PUT，DELETE。

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

GET /people將返回人員列表。

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

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

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

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

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

GET和POST是主要使用的2個方法。

有時我們使用PUT和DELETE：PUT有時用於更新資源，例如更改個人的地址。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的人決定。

tags: [“rest api”, “http protocol”, “endpoints”, “http methods”, “naming conventions”, “responses”, “status codes”]