從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的人決定。