API

從介面與契約理解 API，再依需要閱讀 HTTP、設計風格與具體技術。 本索引不指定主要程式語言或框架。

目前狀態：本索引列出的 16 篇概念文章已整理；各語言、框架與服務的實作範例按需求另行補充。 內容涵蓋五篇共通基礎、三篇共通延伸、五篇 HTTP，以及 REST、gRPC、GraphQL 三篇專題。

查證日期：2026-11-02。分類與閱讀順序是本站的編輯提案，並非通用標準分類。

先分清楚討論範圍

API（Application Programming Interface）不只存在於網路服務。 例如 Python/C API 提供擴充或嵌入直譯器的介面；這類介面不必透過 HTTP 呼叫。 因此不能把所有 API 都理解成網址、請求／回應或 JSON 資料。 參考 Python/C API 導論。

本索引先整理介面提供者與使用者之間的共同問題，再處理不同情境：

HTTP 的協定定位見 RFC 9110 §1。 REST 是架構風格，不能只因使用 HTTP 或 JSON 就稱為 REST；其定義包含一組架構約束。 參考 Fielding 第五章。

gRPC 以服務方法及訊息定義描述遠端呼叫，也支援串流；其 HTTP/2 協定另有具體定義。 GraphQL 定義查詢語言與執行語意，官方文件說明它不要求特定的用戶端／伺服器協定。 因此 HTTP、REST、gRPC、GraphQL 不能當作同一層互斥的四種類別。 參考 gRPC 核心概念、 gRPC over HTTP/2、 GraphQL 規格導言與 GraphQL over HTTP 說明。

建議閱讀順序

1. 介面與契約：先知道誰提供能力、誰使用，以及承諾了什麼。
2. 資料與失敗語意：理解輸入限制、輸出意義與錯誤如何被使用者辨識。
3. 相容性、文件與測試：理解契約如何被記錄、驗證與演進。
4. 選擇情境：處理 HTTP 服務時從資源、表示與訊息開始；遇到特定技術時讀對應分支。
5. 閱讀實作：回到使用中的語言、框架或雲端服務，對照共通概念與實際差異。

這是閱讀建議，可以依問題直接查找，不需要依序完成。

共通概念

以下延伸依情境閱讀，不把每個議題套用到所有 API：

• 身分驗證與授權：在有身分與存取控制需求時，整理身分、操作與資源的關係。
• 逾時、重試與冪等性：以遠端操作為重點，整理重複執行、部分失敗及副作用。
• 集合查詢設計：有集合介面時，整理篩選、排序、分頁與一致性的取捨。

HTTP API

此分支集中處理 HTTP 語意，其他分支引用所需部分。 方法、狀態碼與欄位的定義以 RFC 9110為基礎； 快取規則另見 RFC 9111。

OpenAPI 是與程式語言無關的 HTTP API 介面描述規範，不是所有 API 的統一契約格式。 本次查閱 OpenAPI 3.2.1 的範圍說明。

設計風格與具體技術

• REST 的架構約束：資源、表示、統一介面與超媒體；討論約束與取捨。
• gRPC 的服務與呼叫模型：服務定義、一元呼叫與串流、期限及狀態；區分訊息與通訊層。
• GraphQL 的型別與執行模型：schema、查詢、變更與訂閱；另述 HTTP 對應方式。

各篇先引用共同契約、相容性及失敗概念，再補該技術的規則；不承諾每項技術適用於同一需求。

語言、框架與服務實作

目前以概念文章為主，尚未編寫語言、框架或服務的實作教學；有具體需求時再補充，不預先建立多語言的重複教學。 每篇引用共通概念後，說明該工具的寫法、預設行為、限制與適用版本。 AWS 或其他服務若有專屬驗證、錯誤或重試規則，也在服務文件補充差異。 操作範例須記錄實際驗證情況；本次僅查證文件，未執行服務或程式測試。

相關主題

• 關聯式資料庫：理解儲存層的模型、交易與查詢；API 重試與資料庫提交結果須一起考慮。
• Web 應用資安：將驗證與授權概念延伸到 Session、瀏覽器及資料處理邊界。

參考來源與對應範圍

以下為本次實際查閱的一手來源；可變動的官方導覽頁以查證日期為準。