API是什麼？程式之間的約定與「API串接」

生活中的例子

打開手機的天氣App，馬上就會出現所在地點的預報。不過，做這個App的公司，不一定自己在觀測天氣。它常常是向擁有氣象資料的公司的伺服器詢問：「請給我這個地點的預報。」伺服器是應要求提供資料的電腦。

同樣的事，也發生在其他地方。商店的網站上，有時嵌著Google地圖。登入畫面上，有時排著「使用Google帳戶登入」的按鈕。這些都是一支程式在請別家公司的程式做事。

這時，如果每個人的請求方式都不一樣，就麻煩了。要請求什麼、用什麼寫法請求、回答會以什麼形式回來？把這些事先決定並公開的約定，稱為API（應用程式介面）。它是Application Programming Interface的縮寫。

API是「請求方式」的約定

Interface（介面）是「接觸的地方」「接合處」的意思。也就是說，API是程式和程式接合處所用的約定。重點在於，它不是給人看著畫面操作的約定，而是給程式使用的約定。

約定裡主要寫著下面這些事。

• 可以請求的工作名稱（例：「查詢預報」）
• 請求時要附上的資訊（例：地點和日期）
• 回答的形式（例：氣溫用數字，單位是℃）
• 失敗時的回覆（例：「找不到這個地點」）

請求的一方不必知道對方怎麼計算預報，也能拿到回答。反過來，接受請求的一方只要不改變約定，就能重新打造內部的運作方式。請求的一方可以照常使用。

約定通常會整理成文件。這份文件稱為「規格書」或「API文件」。

Web API：透過網際網路請求

像天氣或地圖這樣，向網際網路另一端的伺服器請求的API，稱為Web API。現在說到「API」，多半是指這種Web API。

大多數Web API，和瀏覽器開啟網頁時一樣，用HTTP這套規則交換資料。在HTTP中，請求的一方送出「請求（request）」，伺服器傳回「回應（response）」。HTTP本身在「HTTPS是什麼？」也有說明。

和網頁不同的地方，在於回應的內容。網頁會傳回給人閱讀的文字和圖片。Web API則傳回程式容易讀取的資料。

我們用一個虛構的天氣API，看看請求和回應的例子。對方的名稱「api.example.com」是保留給說明用的名稱，不是真實的服務。

請求第1行的「GET」，表示「想取得資料」這種請求的種類。這個種類稱為HTTP方法。接著的「/forecast?city=tokyo」是想請求的內容。這裡是在說「預報，關於東京」。

第2行的「Host」是對方伺服器的名稱。從名稱查出機器編號的運作方式，在「DNS是什麼？」中說明。第3行是表示誰在請求的金鑰（後面說明）。

回應第1行的「200」，是表示「成功了」的數字。這個3位數的數字稱為HTTP狀態碼。找不到要求的東西時是404，請求太多時是429，每種結果都有固定的編號。

設計Web API時，廣泛使用一種叫REST的想法。2000年，參與制定HTTP規格的羅伊·菲爾丁（Roy Fielding）在博士論文中為它命名。常見的做法是替每種處理對象（例如預報、訂單）各給一個位址，再用HTTP方法表示取得或刪除等操作。這樣的API稱為REST API。

JSON：程式容易讀取的資料形式

回應後半用「{ }」括起來的部分，是名為JSON的寫法。回應第2行的「application/json」，就是表示內容用這種寫法的記號。它用「:」把「名稱」和「值」連成一組，組和組之間用「,」隔開。名稱和文字的值用「" "」括起來，數字則直接寫。

把例子中的回應整理成表格，就是下面這樣。

請注意，「22」沒有附上單位。是℃，還是美國使用的°F（華氏）？這不是寫在JSON裡，而是寫在API的規格書中。不讀規格書就使用，就會發生這種弄錯單位的事。

JSON的寫法，由2017年的規格RFC 8259所規定。它源自JavaScript這種程式語言的寫法，現在幾乎所有程式語言都能讀寫。

API金鑰：表示「是誰在請求」的鑰匙

很多Web API並不會無限制地接受任何人的請求。它們會替每個使用者或公司，發行一串猜不到的長字元。這稱為「API金鑰」。請求的一方每次請求時，都要附上這把金鑰。

收到金鑰的伺服器，會分辨請求來自哪個使用者。接著判斷這個使用者能不能使用該功能，並計算呼叫次數來決定費用。例如Apple的天氣API叫做WeatherKit。截至2026年10月，每月50萬次以內的呼叫，包含在開發者會員的費用中。

金鑰必須保密的理由，以及保護方法

因此，API金鑰要像密碼一樣保密。傳送時，要使用加密的HTTPS（「加密是什麼？」）。特別要小心的是，把金鑰直接寫在程式的檔案裡。一旦公開那支程式，金鑰也會跟著公開給全世界。

把金鑰放進手機App或網頁裡，也很危險。因為發出去的內容，使用者可以取出來檢查。秘密金鑰只能放在自家的伺服器上，由那台伺服器附上金鑰，再向對方請求。

實際上，外洩事件發生過很多次。保存和公開程式的代表性服務是GitHub。資安公司GitGuardian在2025年3月發表了一份報告。2024年在公開的GitHub上，找到的金鑰、密碼等機密資訊約有2,380萬件。

Google對API金鑰的處理方式，提出了下面這些注意事項。

• 不要把金鑰放進App或網頁的程式裡，也不要放進存放程式的地方
• 替每把金鑰限制可以使用的網站和功能
• 刪除不再使用的金鑰
• 定期把金鑰換成新的

不過，也有一些金鑰，本來就是設計成放在網頁裡、讓人看得到的。例如在商店網站上嵌入地圖用的金鑰，瀏覽網頁的人也看得到。這是另一種金鑰，要靠「只接受來自這家商店網站的請求」之類的限制來保護。金鑰能不能被看到，請以發行單位的說明為準。

次數的限制（速率限制）

很多Web API對一定時間內可以請求的次數設有上限。這稱為「速率限制」。目的是避免少數使用者占滿伺服器，讓其他人只能等待。它也能防止有錯誤的程式不斷重複請求，讓費用暴增。

例如GitHub的API，截至2026年10月，沒有表明身分的請求每小時最多60次。附上使用者的身分憑據再請求，每小時最多可以用到5,000次。

超過上限時，很多伺服器會傳回「429 Too Many Requests（請求太多）」的回應。這個編號是由2012年的規格RFC 6585所規定。回應裡有時還會附上「請在幾秒後再請求」的資訊。設計良好的App會照著做，隔一段時間再重新請求。

「使用Google帳戶登入」的背後

在其他網站「使用Google帳戶登入」時，你並沒有把Google的密碼交給那個網站。輸入密碼的畫面，是Google的畫面。網站收到的，是Google發行的「這個人確實是本人」的證明，裡面不含密碼。

這種做法以名為OAuth的規則為基礎。OAuth是一套不交出密碼，就能允許其他App「使用到這個範圍為止」的規則。2012年，現在的版本OAuth 2.0成為規格。

許可和證明，是用稱為「權杖（token）」的資料來傳遞。它有期限，能使用的範圍也有限，就像通行證一樣。就算外洩，造成的損害範圍和時間也比密碼小。

登入時使用的是OpenID Connect這套規則。它在OAuth 2.0上加入了傳達「是誰」的部分，Google的登入也遵循它。本人的證明，會以稱為「ID權杖」的權杖送達。

API不只用在Web上

API這個詞，在Web API普及之前很久就有人使用了。例如App想儲存檔案時，會向作業系統（OS）請求。作業系統是管理電腦或手機的零件，再借給App使用的基礎軟體。這種請求方式也是API，每種作業系統都不一樣（「作業系統（OS）是什麼？」）。

把常用的功能整理成零件的程式，稱為「函式庫」。例如畫圖表、計算日期之類的零件。函式庫也有API，規定要怎麼呼叫哪個零件。這是在同一台機器裡的呼叫，所以不經過網際網路。

工作上聽到的「API串接」是什麼

在公司裡，常會聽到「把這兩個系統用API串接起來」的說法。意思是讓不同的系統，透過API自動交換資料。這樣就不必由人從一邊的畫面匯出資料，再匯入另一邊。

例如會計軟體自動匯入銀行帳戶的收支明細。在日本，2017年5月通過、2018年6月施行的《銀行法》等修正，建立了這種串接的制度。銀行被要求努力建立體制，以API和記帳、會計服務的公司連接。

其他還有把網路商店的訂單自動通知物流公司等用法。這些都是把外部公司在雲端提供的服務，連接到自家系統的情況（「雲端運算是什麼？」）。

串接前要確認的事

• 哪些資料、往哪個方向流動（如果包含個人資料，也要確認處理的規定）
• 用誰的權限串接，是否只允許必要的範圍（最小權限原則）
• 對方的API停止服務或約定改變時，會發生什麼事
• 呼叫次數的上限和費用
• API金鑰和權杖由誰、在哪裡保管

常見的誤解

從數字來看

規格會使用很久，但次數上限和費用常常因服務的狀況而改變。使用時，請確認提供者當時的說明。

進一步學習

• 下一步的用語：JWT（權杖的一種形式）、Cookie、網頁應用程式防火牆（WAF）
• 用表格看差異：HTTP/1.1、HTTP/2、HTTP/3的差異、IaaS、PaaS與SaaS的差異、靜態連結與動態連結的差異（函式庫的結合方式）
• 試試看長的金鑰為什麼難猜中：密碼暴力破解時間計算工具
• 從基礎讀起：「網際網路怎麼傳送資料？」、「密碼為什麼會被破解？」