API 設計
使用編輯器設計您的 API。
從需求到 API
與大多數技術一樣，API 是解決問題的方案。為了設計出正確的 API，您需要透過回答以下問題，確保您要解決的問題已明確定義：
- 此 API 的目標消費者是誰？
- 消費者將透過 API 操作哪種資訊？
- 消費者將對 API 執行哪些動作？
例如，如果您是一家餐飲外送公司，您可能希望為合作夥伴網路建立一個 API，讓他們能夠瀏覽和搜尋您提供外送服務的餐廳資料庫。
在此範例中，您的 API 目標對象是公司的合作夥伴。他們需要操作有關餐廳的資料，並對資料執行搜尋查詢，且具備特定的篩選和排序功能。
另一個範例：如果您是一家行事曆 SaaS 公司，您可能希望建立一個 API，以便世界各地的其他前端開發人員可以根據您的行事曆系統建立新的行動和 Web 應用程式。
思考 API 的消費者是為他們提供良好開發人員體驗的第一步。這將有助於您的 API 脫穎而出並提高參與度。
構成 API 的元素
設計 API 時會使用四個關鍵概念：
- 資源 是消費者將透過 API 進行互動的元素。資源由路徑唯一識別，該路徑與 API 的端點結合，為網路上的資源提供唯一的位址。例如，Calendars 是對應於行事曆清單的資源名稱，其路徑為 /calendars。
- 作業 是可對資源執行的動作。最常見的作業是 GET (讀取)、POST (建立)、PUT (更新) 和 DELETE。例如，List all Calendars 是在 Calendars 資源上使用 GET 方法的作業名稱。
- 資料類型 是對網路上交換之實際資料的描述。例如，Calendar 是一種資料類型的名稱，它將描述 Calendar 的所有屬性，例如其名稱、擁有者以及對屬於它的事件的參考。List all Calendars 作業會傳回 Calendar 資料類型的清單。
- 元件 是可以在整個 API 定義中重複使用的元素。例如，如果您需要在多個作業中使用相同的查詢參數，您可以將其建立為元件，並在需要的作業中參考它。
構成 API 的其他實用元素包括：
- 端點 是 API 在網路上的主要進入點。端點由配置 (例如 HTTPS) 和主機 (例如 www.calendar-api.com) 組成。
- 文字 區塊可用於自由輸入任何文字 (包括 markdown)，這些文字可以放置在 API 設計中的任何位置。使用文字區塊來解釋驗證和錯誤處理等橫向主題。
- 區段 用於將資源和資料類型進行有意義的群組。使用這些區段可讓您的 API 設計更清晰、對開發人員更友善。您可以將元素拖放到左側面板的區段中，也可以重新排列區段之間的順序。
在 API Designer 中，您將能夠從右上角的 建立新項目 選單建立這些元素。
伺服器 URL 是在一般資訊畫面中建立的。伺服器 URL 可以是 已發佈 或 未發佈。如果已發佈，它會出現在即時文件中。
