設計 API：概覽

到目前為止，您已經學習了如何理解 API，使用現有的 API 規格，以及為開發模擬 (Mock) API。現在是時候採取下一步了：從頭開始設計您自己的 API。

API 設計是規劃和建立定義 API 如何運作的結構、端點和資料模型的過程。設計良好的 API 清晰、一致，且易於開發者理解和使用。

本章將引導您完成在 Apidog 中設計 API 的完整過程，從分析需求到實作您的設計。在本章中，我們將使用 Pet Store API 的 User 模組作為範例——您將逐步學習如何設計一個完整的、具有身分驗證的使用者管理 API。

為什麼要設計 API？

在深入技術細節之前，讓我們了解為什麼 API 設計很重要：

1. 清晰的溝通

設計良好的 API 充當 API 提供者和消費者之間的契約。它清楚地定義了：

有哪些可用的操作

需要什麼資料

預期會有什麼回應

這種清晰度減少了困惑，使協作更加順暢。

2. 更好的開發者體驗

當 API 經過深思熟慮的設計時，開發者可以：

快速理解 API

在沒有大量文件的情況下正確使用它

更快地建立整合

3. 更容易維護

結構良好的 API：

更容易更新和擴充

較不容易發生破壞性變更 (breaking changes)

更容易測試和除錯

4. API 優先 (API-First) 開發

透過在實作之前設計 API，團隊可以：

平行工作（前端和後端）

儘早驗證設計

使用 Mock API 進行開發

您將學到什麼

在本章中，您將學習完整的 API 設計過程，從設定專案到在 Apidog 中實作您的設計：

API 設計入門 — 了解 API 設計的基礎知識，包括 RESTful 原則、API 優先方法和設計最佳實踐。

建立您的第一個 API 專案 — 在 Apidog 中設定新的 API 專案，配置基本設定，並組織您的 API 結構。

分析需求並規劃您的 API — 學習如何在實作之前分析商業需求，識別資源和操作，並規劃您的 API 結構。

設計和實作資料模型 — 設計資料模型並在 Apidog 中將其作為 schema 實作，包括實體、關係和請求/回應結構。

設計端點 — 在 Apidog 中實作您規劃的端點，包括方法、路徑、參數和回應。

使用元件和可重複使用性 — 建立可重複使用的元件（參數、請求體、回應）以保持一致性和效率。

設定身分驗證 — 配置安全方案和身分驗證方法以保護您的 API。

API 設計指南 — 建立並遵循設計標準，以確保您的 API 一致並符合最佳實踐。

先決條件

在開始本章之前，您應該：

了解 API 基礎（在「API 基礎」中涵蓋）

知道如何使用 API 規格（在「使用 API」中涵蓋）

已安裝並設定 Apidog

熟悉基本的 HTTP 概念（方法、狀態碼等）

設計優先 (Design-First) 方法

Apidog 提倡 API 設計優先的方法，這意味著：

先分析需求 — 在設計之前了解您需要建立什麼

規劃您的設計 — 在實作之前識別資源、操作和資料模型

在編碼之前設計 — 在編寫任何程式碼之前建立完整的 API 規格

使用規格 — 建立符合 OpenAPI 的規格作為單一真實來源

迭代和驗證 — 使用 Mock API 測試您的設計並儘早獲得回饋

邊設計邊記錄 — 文件會從您的設計中自動生成

這種方法確保您的 API 經過良好規劃、一致且準備好進行實作。關鍵是從需求分析和設計規劃開始——這是使其他一切成為可能的基礎。

準備好開始設計您自己的 API 了嗎？從 API 設計入門開始，學習基礎概念和原則。

為什麼要設計 API？#

1. 清晰的溝通#

2. 更好的開發者體驗#

3. 更容易維護#

4. API 優先 (API-First) 開發#

您將學到什麼#

先決條件#

設計優先 (Design-First) 方法#