Logo
後端:邏輯、資料與服務架構

API:幫你傳話的店員

上一課學會了請求與回應怎麼一來一回,這一課看你每次都在跟「誰」講話:API。 想像巷口的手搖飲店:你(用戶端)不會自己闖進後場搖飲料,你只走到櫃檯跟店員點單; 店員把訂單送進後場(後端),做好了再端回櫃檯給你。 這個站在櫃檯、幫兩邊傳話的店員,就是 API:你不必懂後場怎麼搖,只要會點單、會收飲料。下面先點一杯:選好甜度、冰塊、加料,按「送出訂單」,盯著這一趟怎麼跑,注意你只走到櫃檯為止。
BOBA BAR點單
No. 042
珍珠奶茶(招牌)$60
甜度SWEETNESS
冰塊ICE
加料TOPPING
小計 $70

BOBA BAR

後場(後端)
服務生(API)
你(用戶端)
選好規格,按「送出訂單」

訂單:你要什麼(請求)

{ "品項": "珍珠奶茶", "甜度": "全糖", "冰塊": "正常冰", "加料": "珍珠" }……(還沒點)

送回:結果在這(回應)

200 OK 珍珠奶茶(全糖・正常冰・加珍珠)……(還沒做好)

如果沒有 API:走進一間沒有菜單的店

剛剛點單那麼順,是因為櫃檯貼著菜單:能點什麼、怎麼客製、多少錢,都白紙黑字寫好,這就是 API 事先講好的「可以怎麼問」。 現在走進另一間店:沒有櫃檯、沒有菜單,也沒有幫你傳話的人,只有後場一個背對你、自顧自搖飲料的吧檯手。 你只能用下面的字塊(或直接打字)拼一句話,走上前對著後場喊喊看。多問幾次,體會一下沒有講好介面的世界長什麼樣。
歡迎光臨~
後場(後端)
你(用戶端)
拼一句話,開口問問看

端點:API 菜單上的每一道品項

回到有 API 的世界。真實的 API 就是把「可以怎麼問」寫成一條一條的端點(Endpoint):每條端點是一種服務,寫法是方法+路徑,方法最常見兩種:GET 是跟它要資料、POST 是送資料過去。 左邊是手搖飲店的官方點餐 App,從看菜單、下單、查進度到評分,照著按完一輪;每按一下,右邊就會亮出這一下背後打的是哪條端點、送了什麼、拿回什麼。

BOBA BAR

官方點餐 App

歡迎回來

先看看今天有什麼

api.bobabar.example 的端點(App 能問的所有問題)
GET/menu拿菜單:現在有什麼可點
POST/orders下單:送出一筆新訂單
GET/orders/42查單:42 號做好了沒
POST/reviews評分:幫這一單打星星

還沒有任何呼叫。在左邊的 App 按「看菜單」,看它背後打了哪一條端點。

回應拆開看:JSON 裡面裝了什麼

剛剛每條端點拿回來的貨,包裝幾乎都是同一種:JSON,一包貼了標籤的資料,每一行都是「鍵: 值」。 值只有五種長相:字串、數字、布林、陣列、物件,而且物件裡可以再裝一層。 左邊是查單拿回的那包 JSON、右邊是 App 用它畫出的取餐卡:點任何一個值(或畫面上任何一塊),看資料跟畫面怎麼一一對應。
GET /orders/42 的回應內文JSON
{
"單號": ,
"狀態": ,
"飲料":
"品項": ,
"甜度": ,
"價格":
,
"加料": ,
"已付款":
}
BOBA BAR取餐卡(App 畫面)
#42可取餐
珍珠奶茶半糖$60
加料珍珠椰果 已付款

畫面上的每一塊,都是左邊那包 JSON 裡挖出來的某個值。點點看,兩邊會互相對亮。

回應.飲料.品項

字串(帶引號的文字):要挖深一層的值,就一層一層點進去:先進「飲料」這包,再拿「品項」。畫面最大那行字就是它。

實戰:串一支真的 API,查珍奶店開了沒

端點、JSON 都認得了,來串一支真實世界的 API:Google 的 Places API,讓 App 回答一個超實際的問題:「現在殺去 BOBA BAR,到底開著沒?」 這也是你第一次看到串別人家 API 的完整流程:先到 Google Cloud 啟用 API、申請金鑰,再照文件組請求、呼叫、拆回應。下面把 GCP 的畫面搬進來,五步照著走完一趟。
API 串接集點卡集滿五點,學會串一支真 API
Google Cloudmy-boba-app ▾API 和服務 › API 程式庫

想查店家「現在開著沒」,Google 提供的服務叫 Places API。第一步:到 GCP 的 API 程式庫把它啟用,等於告訴 Google「我的專案要用這支 API」。

places
Places API (New)

查詢地點資訊:店名、地址、評分、營業時間(含「現在營業中嗎」)。

1 / 5・啟用 API

外面的世界:你能直接串的熱門 API

剛剛串的 Places 只是冰山一角。外面有一整條街「別人開好的店」,每家都把自己的本事包成 API 等你串:AI 對話有 ChatGPT、臺灣天氣有中央氣象署、音樂資料有 Spotify;收錢有 Paddle、發訊息有 LINE。 你的 App 想要什麼超能力,多半不用自己造,找到對的店、照菜單點就有。

點下面的品牌磚逛一圈:看每家在做什麼生意、憑證去哪拿、菜單上有哪幾條端點。

ChatGPTapi.openai.com

把 ChatGPT 的腦袋接進你的 App:對話、生圖、聽打全都是端點。

POST/v1/chat/completions

丟對話訊息進去,拿 AI 回覆回來(ChatGPT 同款能力)

POST/v1/images/generations

一句描述,生一張圖

POST/v1/audio/transcriptions

上傳錄音檔,回逐字稿

API Key 去這裡設定:platform.openai.com

重點回顧

從一杯珍奶點到串真實的 Google API,把「API 是什麼」走了一整趟。帶走這四個重點:

  1. 1
    API=講好的介面,後端是黑盒子
    你從頭到尾只跟「櫃檯店員」打交道:照講好的方式送請求、收回應。後場怎麼搖飲料,你不用懂、也碰不到。
  2. 2
    沒講好介面,連能點什麼都要用猜的
    沒有菜單的店,問三次才問出招牌只有大杯的。菜單就是 API 文件:「可以怎麼問」白紙黑字寫死,雙方才第一次就對得上。
  3. 3
    端點=方法+路徑,App 每個動作打一條
    GET 是要資料(拿菜單、查訂單)、POST 是送資料(下單、評分)。看菜單、查進度、給星星,背後各是一條端點在跑。
  4. 4
    回應是 JSON,照這套流程串誰都一樣
    鍵: 值、可以巢狀,格式固定、內容可變,程式照鍵取值畫上畫面。啟用 → 拿金鑰 → 組請求 → 送出 → 拆結果,同一套流程能串 Google,也能串 AI 模型、Stripe、LINE。

隨堂檢測

一個 App 下單時固定呼叫 POST /orders,並從回傳的 JSON 讀取 orderId 和 status。後端後來整套重寫,但這些都沒有改。App 最可能需要怎麼調整?

想想 App 真正依賴的是後端裡面的程式,還是 API 對外提供的呼叫方式與資料格式。

0:00 / 0:00
0:000:00
下一課