Martha Lane Fox報告希望政府可以“經由 API 提供數位服務和內容給第三方使用，像是經銷商與售商店一樣”。

本篇內容說明如何以 API 方式提供數位服務。

指引

透過使用 API 來製作 API

當製作 API 時，要小心為錯誤的對象以錯誤的方式製作了錯誤的產品。

這在缺乏開發者社群對 API 提出需求時特別容易發生。

確定 API 可用性的最簡單方式是利用此 API 製作一個網站。

製作網站時會考量如何讓資源以可書籤化方式來呈現最佳化的內容和資料，並確保資料會以人類和機器都可讀方式呈現。

成為 API 的使用者不只可以驗證 API，還可以讓服務在網路上曝光。

只使用網路

想像 API 是網站的一部份。

從人可以閱讀的網頁提供機器可讀的格式，並且讓代理人 (agent) 可輕鬆產生 URLs 連到人類可讀格式的頁面。

使用標準格式的內容，並且追隨網站慣例以進行認證。

建立可以享有眾多開發者社群的擁戴和支持，並且同時可以讓全球使用者使用的服務並不容易。當開放和封閉的技術主要專注於機器間溝通，它們並沒有網路的互通性、可達性和規模放大的能力。

標準化是有力的協定，沒有比網路可以更快速建立和接受協議的地方。網路的核心技術如 HTTP (Hypertext Transfer Protocol) 和 URLs (uniform resource locator) ，以及正在竄起的標準如 JSON 和 OAuth ，讓網站從零售商的櫥窗變成批發商，達到設計準則所說建立數位服務，而不只是架設網站。

讓網站的每個地方都有可以加入書籤的網址

讓資料以一組資源露出，給每個地方和集合提供乾淨的網址。

只在有無次序參數時在網址使用詢問字串 (query string)，如搜尋頁的參數。

考慮為不同規模的資源產生不同網址。例如，/member.json 可以回傳名字列表，而 /members.json?detail=full 可回傳列表中每一位成員的詳細資料。

這些規則可以讓資訊以網路之外的方式傳遞，像是提醒 email、簡訊 (SMS)、或其他訊息格式，並可連結回網站上的相關內容。

以 Tim 所想的方式使用 HTTP 方法

確認所有 HTTP GET 要求是安全的，改變狀態的動作需使用 POST、PUT 或 DELETE 方法。

使用 PUT 和 DELETE 方法時要小心，因為他們通常被防火牆、內部網路代理伺服器 (proxy)、飯店無線網路以及手機營運商擋住，永遠要提供 POST 的替代方法。

避免使用尚未完整定義的 HTTP 方法，例如 PATCH。

格式是為了使用者

以可讀的 HTML 方式提供內容，並提供機器可讀方式的連結：

• 可讓大多數程式語言處理的 JSON
• 為客戶端 Javascript 提供可跨網域分享 (Cross Origin Resource Sharing, CROS) 的 JSONP 和 JSON
• 為了匯入表格提供 CSV
• 訊息來源 (feed) 以 Atom 格式提供

如可能，也可提供其它特殊格式，例如：

• 為活動提供 iCalendar
• 為名字和地址提供 vCard
• 為地理資料提供 KML 和 geoRSS
• 為播放列表提供 m3u

這些建議是根據資料和內容的發表格式的一般準則。

包括不同格式的超連結，包括連結標頭(link header) 和在內容中。

也可以考慮使用語義化標記 (semantic markup) 將 metadata 編碼到 HTML 內容裡：Microformats, RDFa 或 schema.org

由 API 支援的輸入格式會根據動作的複雜度而定。但是最好可以包括 application/x-www-form-urlencoded 設定，所以輸入可以透過簡單的 POST 表單來完成。

命名法則

整個 API 中對欄位、格式和路徑的命名應一致。使用讓其他人可以輕易了解的方式命名。盡可能使用網路上一般常用命名方式，以及使用 Microformats 的命名規則。

透過發現和例子來建立文件

建立透過連結露出資料、透過 HTML 格式露出服務的網站，鼓勵探索從而透過超文件 (hypertext) 有所得。

使用例子提供 API 文件。收集人們如何使用 API，特別是連到任何開源專案的計劃或程式語言庫。提供簡單格式以供讀取，例如 The Guardian API 閱讀器。

明確標示所提供內容

在網頁或其他文件中清楚標示安全性、可用性、呼叫限制（rate-limiting）、可預期回應，以及所提供資料，所以用戶可以計劃他們如何使用 API。

預設為公開

降低其他人使用資料的障礙，對公開資料不要要求註冊或使用 API 金鑰 (API Key)。

公開資料會提高使用資料與服務的人數，從而讓使用者反饋變為解決問題的動力，得以修正服務和資料，如此成為正向循環。

對需要認證的敏感資料使用 HTTPS 加密 (Hypertext Transfer Protocol Secure)，以及如基本驗證或 OAuth 等標準認證方式，選擇可基於內容的敏感性。

務實考量服務的演進

建立服務時考量未來相容性並不常見。Postel’s定律解釋了網際網路會演化的能力，但你不應該忽略錯誤或無效的內容格式。

保留舊版本的相容性，提供空白欄位的預設值。避免語義內容的改變，例如不要改變代表頁面標題 (title of page) 的標題欄位 (title field)，變成個人工作職稱(job title)的名字。

如果革命性改變無法避免，以改變網址來通知此決定性變化。當 URL 改變時，要注意舊用戶，或許可使用轉址。Cool URI 不會改變。

使用 API

不需要自己做每件事 (你也不會樣樣通)。有時候服務所需功能是由組織的其他部門，或政府的其他部會或可靠第三方以 API 方式提供。

大部分數位服務建立於許多 API 上。這讓服務的每一部分專注在其核心功能，而不是持續重新發明已存在的輪子。

程式碼整合

當使用 API時，需注意程式碼和 API 整合部分的整潔和獨立性。這點很重要，所以在換提供者和版本更新時不需要改變核心程式碼。

在 GDS 鼓勵使用專注在系統界面和配對程式碼的配接程式碼 (adapter code)。這將提供測試內容和 API 所提供服務的連結。

測試

應仔細考量如何測試服務整合。在每日開發中，測試程式碼應該不要常常去呼叫第三方服務 (計算上或者收費考量)，所以應該想辦法提供這些 API 的替代版本。然而在完整系統測試時，你會需要測試整個流程，所以應該為此建立自動測試。

許多 GOV.UK 出版的應用寄送提醒 email 給內容設計師。當測試時，會替換原本的 email 服務，避免寄送過多假 email。這讓測試可在不依靠外部服務進行。

很多平台包括和 Google 分析互動。測試時，寄送事件到 Google，等待回應然後繼續，接著檢討結果的方式並不實際。開發者建立模擬服務可以平行測試並 Google API 的虛擬版本，讓我們檢視正確資料是否送出。

發佈系統使用單一登入服務。大部份的測試和該服務的互動都是模擬的，所以應用測試是在獨立環境進行，另外有使用虛設帳號的預覽系統，確定驗證流程可以正確進行。

授權應用工具 (Licence Application Tool) 和數個付款服務綁定。使用測試帳號來確認使用可以和這些服務傳送連結，傳送正確資料並完成付款。

服務協定和彈性

若服務相依於第三方 API，其可用性會和第三方綁定。在一些狀況這是可接受的，但通常需要備用計劃。

備用計劃細節和服務相關。可能是需要提供另一種服務，或動作先暫停之後再進行。這可以是自動排程，由軟體監控並重啟，或者是手動排程，另有人跟進並收集細節。

需讓使用者了解實際狀況。如果第三方支付無法使用，你可能需要之後再進行結賬。這代表你無法提供原本所說的付款服務。

延伸閱讀

• API Craft 是討論發佈 API 的公開活躍討論區。
• The Open Web Application Security Project (OWASP)有大量使用需保密資訊建立 API 的資料，包括 REST Security Cheat Sheet。
• 白宮的 API standards 和這套規範大致相通。

翻譯時所查資料
what is cool URI
RESTful世界里的Cool URI,
Tim Berners-Lee,
RESTful 應用程式,

譯者：Pei Cheng
校稿者：Sharon Wang
原始出處：https://www.gov.uk/service-manual/making-software/apis.html