一、今天的定位

Day 7 用 Dify 完成了第一個 AI 英文情境生成器，也代表第一階段正式結束。今天原本規劃是進入第二階段、開始做角色扮演功能，但因為後面 Day 15 之後要用 FastAPI 串接前後端，而 API 的觀念其實是貫穿整個系統的基礎，所以先插進來把這塊搞懂，讓之後看 FastAPI、看 Dify 的「存取 API」頁面時不會只是照抄。

今天不寫程式，純粹建立觀念。

二、API 到底是什麼

API 全名是 Application Programming Interface（應用程式介面）。

最直覺的理解方式：API 是兩個系統之間溝通的約定。

一個系統想跟另一個系統要資料或請它做事，不可能直接把自己的程式碼塞進對方裡面執行，而是雙方先講好「你要用什麼格式跟我說話，我才聽得懂，我也會用什麼格式回你」。這份「講好的規則」就是 API。

日常生活的比喻是餐廳點餐：顧客不會自己跑進廚房煮菜，而是透過服務生（API）用固定的方式點餐（傳送請求），廚房做好之後再透過服務生把餐點送出來（回傳結果）。顧客不需要知道廚房裡發生了什麼事，只需要知道怎麼點餐、會拿到什麼。

放回這個專題的情境：Day 7 做的 Dify 應用，本質上就是一個 API。使用者輸入情境描述，Dify 內部跑了一串 LLM 呼叫、Prompt 組裝、格式處理，但呼叫端完全不需要知道這些細節，只需要知道「傳什麼參數進去、會拿到什麼 JSON 回來」。

三、幾個一定要先分清楚的名詞

Request（請求）與 Response（回應）

呼叫 API 的一方送出 Request，被呼叫的一方回傳 Response。這是最基本的一問一答關係，之後看任何 API 文件都是圍繞這兩個概念在描述。

Endpoint（端點）

API 提供的每一個「可以呼叫的網址」。例如 Day 7 記下的 https://api.dify.ai/v1/completion-messages，這串網址就是一個 endpoint。一個系統通常會有很多個 endpoint，各自負責不同的功能。

HTTP Method（方法）

告訴伺服器這次呼叫想做什麼動作，最常見的四種：

GET：要資料，不改變任何東西，例如查詢天氣
POST：送出新資料，讓伺服器建立或處理東西，例如 Day 7 送出情境參數去產生內容
PUT / PATCH：更新已存在的資料
DELETE：刪除資料

Day 7 呼叫 Dify 用的就是 POST，因為那是在「送出參數，請求 AI 產生新內容」，不是單純查詢。

Headers（標頭）

隨著 Request 附帶的額外資訊，不是主要內容本身，但伺服器需要靠它判斷怎麼處理這次請求。最常見的兩個：

Authorization：身分驗證，Day 7 用的 Bearer app-xxxxxxxxxxxx 就是放在這裡，告訴 Dify「這是誰在呼叫我，這個人有沒有權限」
Content-Type：告訴伺服器這次送的內容是什麼格式，最常見是 application/json

Body（主體）

Request 真正要傳送的資料內容。Day 7 送進去的 scenario、level、focus 這些參數，就是放在 Body 裡面，通常用 JSON 格式包裝。

Status Code（狀態碼）

伺服器回應時附帶的三位數代碼，用來表示這次請求的結果：

範圍 代表意義 常見例子
2xx 成功 200 成功、201 建立成功
4xx 呼叫端的問題 401 沒有權限、404 找不到、429 太頻繁
5xx 伺服器的問題 500 伺服器內部錯誤

之後測試 API 出錯的時候，第一件事就是先看狀態碼落在哪個區間，能省下大量排錯時間。

四、為什麼要用 JSON

API 之間傳遞的資料，絕大多數用 JSON（JavaScript Object Notation）格式。

原因很單純：它同時對人類好讀、對程式好解析，而且幾乎所有程式語言都內建支援。Day 7 設計的情境生成器輸出，本質上就是一份精心設計的 JSON 結構——這不是巧合，而是因為情境生成的結果最終要被 Day 15 之後的後端程式讀取使用，JSON 是最自然的傳遞格式。

五、把今天的觀念對回 Day 7 做過的事

回頭看 Day 7 記下的那段 curl 指令，今天學的每個名詞其實都已經出現過：

https://api.dify.ai/v1/completion-messages 是 endpoint
-X POST 是 HTTP Method
-H 'Authorization: Bearer app-xxxxxxxxxxxx' 是 Header，做身分驗證
-H 'Content-Type: application/json' 也是 Header，說明送的是 JSON
-d '{...}' 裡面包的 inputs 內容就是 Body
送出去之後拿到的那份情境設定 JSON，就是 Response

也就是說，Day 7 其實已經完整跑過一次 API 呼叫的流程，只是當時是照著做，不完全清楚每個環節在幹嘛。今天算是把那一次操作「補上理論」。

六、今天的小結

今天沒有新增功能，也沒有寫程式，但這塊觀念補齊之後，接下來看任何工具的 API 文件——不管是 Dify、之後要接的翻譯 API，還是 Day 18 要自己動手做的 FastAPI——都能直接對照「這是 endpoint、這是 method、這是 body」，不會再只是照著範例貼貼改改。

七、下一步

接下來會回到第二階段的主線：設計英文 Role Play 的 Prompt，讓 Day 7 產生的情境設定真正變成一場可以來回對話的角色扮演。