API 設計

從需求到 API

就像大多數技術一樣，API 是解決問題的方案。若要設計出合適的 API，您需要透過回答下列問題，以確保清楚定義您要解決的問題：

• 此 API 的目標取用者是誰？
• 取用者將透過 API 操作哪種類型的資訊？
• 取用者會對 API 執行哪些操作？

例如，如果您是一家美食外送公司，您可能會想為合作夥伴網路建置一個 API，讓他們能夠瀏覽並搜尋您提供外送服務的餐廳資料庫。

在此範例中，您的 API 是以貴公司的合作夥伴為目標對象。他們需要操作餐廳相關資料，並對資料執行搜尋查詢， 同時具備特定的篩選與排序功能。

另一個範例：如果您是一家行事曆 SaaS 公司，您可能會想要建置一個 API，讓全球的其他前端開發人員能夠以您的行事曆系統為基礎，建立新的行動與網頁應用程式。

為您的 API 取用者著想，是為他們提供良好開發者體驗的第一步。這將有助於讓您的 API 脫穎而出，並提升參與度。

組成 API 的元素

設計 API 時會使用四個核心概念：

• 資源是您的取用者透過您的 API 進行互動的元素。資源由路徑進行唯一識別，該路徑與 API 的端點結合後，可為網路上的資源提供唯一位址。例如，Calendars 是對應至行事曆清單的資源名稱，其路徑為 /calendars。
• 操作是指可對您的資源執行的動作。最常見的操作包括 GET (讀取)、POST (建立)、PUT (更新) 以及 DELETE。例如，List all Calendars 是在 Calendars 資源上使用 GET 方法的操作名稱。
• 資料類型是對透過網路交換之實際資料的描述。例如，Calendar 是一個資料型別的名稱，用來描述 Calendar 的所有屬性，例如其名稱、擁有者，以及對屬於它的事件的參照。「列出所有行事曆」作業會傳回 Calendar 資料類型的清單。
• 元件是可在整個 API 定義中重複使用的元素。例如，如果您需要在多個操作中使用相同的查詢參數，您可以將其建立為元件，並視需要在任意數量的操作中參照它。

還有其他組成 API 的實用元素：

• 端點是您的 API 在網路上的主要進入點。端點是由配置 (例如 HTTPS) 和主機 (例如 www.calendar-api.com) 所組成。
• 文字區塊可用來自由輸入任何文字（包括 markdown），並可放置在您的 API 設計中的任何位置。使用文字區塊來說明 身分驗證和錯誤處理等橫向主題。
• 區段可用於將資源與資料類型進行有意義的分組。使用這些來讓您的 API 設計更清晰，並對開發人員更友善。您可以將元素拖放至左側面板的區段中，也可以重新排列各區段之間的順序。

在 API 合約中，您可以從右上角的 建立新項目選單建立這些元素。

伺服器 URL 會在一般資訊畫面中建立。伺服器 URL 可以是 已發布或 未發布。如果已發布，它會出現在即時說明文件 (Live Documentation) 中。