API —
程式跟世界說話的方式

你每天都在用 API

API（application programming interface）可以先想成服務窗口。你不是走進銀行金庫自己搬錢，也不是衝進餐廳廚房自己煎牛排；你會到櫃台說明需求，櫃台確認格式正確，後面的人處理完，再把結果交回來。程式也一樣。你的手機 App 通常不會自己保存全世界的天氣資料、地圖資料、付款資料。它會把需求送到某個服務窗口，請對方查好、算好、驗證好，再把答案拿回來顯示。

這跟 ch15 學過的 JSON 很有關係。當程式要跟程式說話，不能只丟一句人話：幫我查台北天氣。它要用雙方都看得懂的格式，把城市、日期、使用者身分、想要的資料種類放進請求裡。對方回覆時，也會用固定格式把結果包回來。JSON 就常常是這個包裝盒。你可以把 API 想成服務窗口，把 JSON 想成窗口遞來遞去的訂單紙。

對完全不寫程式的人來說，API 最重要的不是背縮寫，而是建立一個畫面：每次你按下查詢、登入、付款、翻譯、生成圖片，前端（frontend）都可能正在把你的需求送去外面的服務。前端是你看得到的店面，API 是店面對外溝通的窗口。你學會看這個窗口，就能理解為什麼有些功能需要網路、為什麼錯誤訊息會寫 404、為什麼 AI 幫你串接服務時一定要看文件。

function weatherCafe(city) {
  const menu = {
    台北: { city: '台北', weather: '多雲', temperatureC: 28 },
    台中: { city: '台中', weather: '晴時多雲', temperatureC: 31 }
  };
  return menu[city] || { error: '查不到這個城市' };
}

const response = weatherCafe('台北');
console.log('API 回應：', response);
console.log('畫面要顯示：' + response.city + '現在' + response.weather + '，' + response.temperatureC + '度');

餐廳模型：服務生、廚房與菜單

我們用餐廳模型把 API 說清楚。你坐在桌邊想點餐，桌邊這一側就是前端（frontend）：按鈕、表單、選單、手機畫面都在這裡。服務生或點餐窗口就是 API：它負責接收你說的需求，檢查你有沒有講清楚，然後把需求送進廚房。廚房是伺服器（server），真正做事的地方。倉庫是資料庫（database），裡面放著菜單、庫存、訂單、會員資料。你通常不會直接跟廚房講話，更不會直接翻倉庫；你透過服務窗口。

菜單就是 API 文件（API documentation）。文件會告訴你：這家店有哪些窗口可以用、每個窗口要填什麼、可以用什麼方式點、成功會拿到什麼、失敗會收到什麼錯誤。沒有菜單就亂點，服務生只會聽不懂。這也是為什麼跟 AI 討論 API code 時，不要只說「幫我接天氣 API」。你要把文件貼給它，像把菜單交給實習生模型（AI），請它照上面的品項、格式、注意事項做。

一個成熟的 API 通常不只一個窗口。天氣服務可能有查現在天氣、查未來七天、訂閱下雨通知三個窗口；付款服務可能有建立付款、查付款狀態、退款三個窗口。每個窗口都有自己的規矩。你如果把「查天氣」的格式拿去「建立付款」，就像拿早餐店菜單去銀行櫃台點蛋餅，對方不是不友善，而是你走錯窗口。

const apiMenu = {
  '/weather/current': '查現在天氣',
  '/weather/forecast': '查未來三天天氣',
  '/weather/subscribe': '訂閱天氣提醒'
};

console.log('天氣咖啡廳菜單：');
for (const endpoint in apiMenu) {
  console.log(endpoint + ' -> ' + apiMenu[endpoint]);
}

Request 拆開看：endpoint、參數、方法

請求（request）就是你交給服務窗口的訂單。它至少常見三個部件。第一個是 endpoint，也就是你要找哪個窗口；在網址裡常像 /weather/current 這種路徑。第二個是參數（parameter），也就是你要補上的細節；例如城市是台北、日期是今天、幣別是台幣。第三個是方法（method），也就是你想做的動作類型。最常見的是 GET 和 POST。GET 像看菜單或查資料：我想知道台北天氣。POST 像下訂單或新增資料：我要建立一筆報名資料。

GET 和 POST 不用背成冷冰冰的規則，先抓住意圖。只是讀資料，通常偏 GET；會造成新增、送出、付款、報名、留言，通常偏 POST。這個差別很重要，因為你問 AI 時，如果只說「幫我打 API」，它可能猜錯。你可以更精準地說：請用 GET 呼叫 /weather/current，帶 city 參數，讀回 JSON 後顯示 temperatureC。這句話比「幫我串天氣」清楚很多。

參數也有位置差異。有些參數會接在網址後面，像 ?city=台北；有些會放在請求內容裡，特別是 POST 常見。你不必現在背所有細節，但要知道文件會寫。看到文件寫 required，就代表必填；optional 就代表可填可不填。純 vibe coder 常常把錯誤丟回給 AI 亂重試；你會先看訂單是不是填錯窗口、漏填參數、用錯方法。

function buildRequest(method, endpoint, params) {
  return {
    method: method,
    endpoint: endpoint,
    params: params
  };
}

const request = buildRequest('GET', '/weather/current', { city: '台北', unit: 'celsius' });
console.log('送出的 request：');
console.log(request);
console.log('意思：用 ' + request.method + ' 到 ' + request.endpoint + ' 查 ' + request.params.city + ' 的天氣');

Response 拆開看：狀態碼與 JSON

回應（response）是服務窗口處理完交回來的結果。它通常分成兩個你一定要會看的部分：狀態碼（status code）和內容。狀態碼像服務生先給你的短句：200 表示好了，401 表示你沒有出示會員卡或身分不對，404 表示沒有這道菜或找不到這個窗口，500 表示廚房自己出問題。這些數字不是拿來嚇人的，它們是在幫你定位問題。

內容常常是 JSON。成功時，JSON 可能長得像一張整理好的小卡：城市、溫度、天氣、降雨機率。失敗時，JSON 也可能回一段錯誤說明，例如 { "error": "missing_api_key" }。你在 ch15 已經看過物件和清單，現在它們開始有真實用途：程式收到 JSON 之後，可以挑出某個欄位放到畫面上，也可以根據錯誤欄位顯示不同提醒。

會看 response 的人，除錯速度會快很多。畫面沒出現資料，不代表整個程式壞了。你可以問：有送出 request 嗎？response 的狀態碼是多少？如果是 404，是 endpoint 寫錯還是城市不存在？如果是 401，是不是 key 沒帶？如果是 500，也許你的前端訂單沒錯，是對方廚房出問題。這種定位能力，是藍帶開始要建立的系統感。

實作時還有一個小習慣：不要只看畫面，要看原始 response。畫面可能只顯示「失敗」，但 response 會告訴你是缺欄位、缺 key、走錯窗口，還是服務暫時壞掉。你把這段貼給 AI，請它根據不同狀態碼顯示不同訊息，使用者就不會被一個籠統錯誤卡住。

function explainStatus(status) {
  if (status === 200) return '成功：資料回來了';
  if (status === 401) return '身分問題：缺 API key 或 key 不對';
  if (status === 404) return '找不到：endpoint 或資料不存在';
  if (status === 500) return '伺服器問題：廚房出狀況';
  return '其他狀態：請查 API 文件';
}

const responses = [200, 401, 404, 500];
for (const status of responses) {
  console.log(status + ' -> ' + explainStatus(status));
}

API key：會員卡，不是公告牌

API key 可以想成會員卡或通行證。很多服務不是任何人都能無限使用，因為查資料、傳簡訊、跑 AI 模型、刷卡驗證都需要成本。服務商會發給你一串 key，程式帶著它去窗口，對方才知道是誰在使用、用量算在誰身上、權限到哪裡。這裡有一條硬規則：真正的 API key 不要貼到公開網頁、公開 GitHub、課堂截圖、社群貼文，也不要直接丟給不可信的工具。

為什麼這麼嚴重？因為 key 洩漏後，別人可能拿你的會員卡去狂點餐，帳單算你的。真實世界裡，雲端服務、簡訊服務、AI 模型服務都發生過 key 被公開後遭大量使用，幾小時就產生高額費用。這章不教攻擊，只教防守常識：看見文件要求 key，就先問這個 key 應該放在哪裡；如果是公開給使用者下載的前端 code，通常不該放真正秘密。

你現在不必學完整後端部署，但要有警覺。公開頁面上的 JavaScript，別人可以看見。把 key 寫在那裡，就像把會員卡貼在餐廳門口。比較安全的做法通常是：前端把需求交給你自己的後端，後端再帶著 key 去呼叫真正服務。你問 AI 時可以說：不要把 API key 寫進前端，請示範用後端環境變數保存，前端只呼叫我的後端 endpoint。 即使你還不會全部實作，這句話已經能讓 AI 往正確方向走。

function maskKey(key) {
  if (!key || key.length < 8) return 'key 太短或不存在';
  return key.slice(0, 4) + '...' + key.slice(-4);
}

const apiKey = 'DEMO-KEY-2026-ONLY';
console.log('顯示給人看的 key：' + maskKey(apiKey));
console.log('提醒：真正的秘密 key 不要放在公開前端 code 或公開貼文。');

跟 AI 討 API code 的正確姿勢

API 是 AI 協作很容易翻車的地方，原因不是 AI 笨，而是你給的菜單不夠。每家 API 的 endpoint、參數名稱、key 放法、回應格式都不同。你只說「幫我串 Google 登入」或「幫我接天氣」，等於叫實習生模型去一家沒看過菜單的餐廳幫你點菜。它可能猜一個看起來合理的 endpoint，但真實服務根本沒有那個窗口。

比較好的做法是把 API 文件中相關段落貼給 AI，並要求它先摘要再寫 code。你可以固定用這個順序：第一，貼文件；第二，說明你要完成的使用者動作；第三，指出要用哪個 endpoint 和 method；第四，列出必要參數；第五，要求它處理 200、401、404、500 四種回應；第六，提醒不要公開 API key。這不是多此一舉，而是把任務從「憑感覺做一個功能」變成「照菜單完成一張訂單」。

你也可以要求 AI 回答時分成三塊：先解釋資料流，再給 code，最後給驗證清單。資料流讓你看懂前端、API、伺服器誰負責什麼；code 讓你執行；驗證清單讓你知道怎麼檢查，而不是只能祈禱。從這章開始，你問 AI 不再只問畫面怎麼做，而是能問：request 長什麼樣？response 怎麼讀？錯誤狀態要怎麼顯示？key 放哪裡才安全？這就是產品力的入口。

const apiDocsSummary = {
  endpoint: '/weather/current',
  method: 'GET',
  requiredParams: ['city', 'apiKey'],
  successFields: ['city', 'weather', 'temperatureC', 'rainChance']
};

const prompt = '請根據這份 API 文件寫前端呼叫範例：' + JSON.stringify(apiDocsSummary) + '。請處理 200、401、404、500，並且不要把真正 API key 寫死在前端。';
console.log(prompt);

檢查一下這章