政府網站營運交流平台 - 國家發展委員會
:::

Open API應用簡介

點閱次數:1081     資料來源:國家發展委員會     發佈日期:

Open API係指一個可公開取得的應用程式介面,提供開發人員透過程式化存取一個專有的軟體應用程式。API是管理一個應用程式如何和另一個應用程式溝通與互動的一組要求,它也可以允許開發人員存取一個程式的特定內部功能。簡單地說,API允許一個軟體跟另一個軟體交互作用,因此,可以讓組織內部的開發人員與外部開發人員註冊使用[1]。相對地,Private API僅提供內部開發人員使用,無法讓外部的開發人員存取使用,因此,將導致產生相容性的議題及更新速度慢等問題[2]

為什麼要提供Open API呢,政府部門主要可以獲得以下幾點的好處[3]

1.增加服務的可及性:讓其他第三方單位可以整合或簡化機關所屬的資料與內容。

2.節省時間:機關可以只要更新一次資料或內容,API可以自動地在網站、行動平台與社群媒體等多個位置上自動更新。

3.節省成本:讓第三方創新者使用資訊和服務而創造新的、有用的產品,而此產品是超出機關的範圍或預算之外。

4.加速產品的開發:藉由對於內容的重整和開放使用,讓內部團隊和合作單位增進打樣與使用速度,加速產品的開發。

5.建立市場:藉由改善政府資源的使用如健康、經濟、能源、教育、環境資源,提供企業在此基礎上建立市場。

以上的好處,前面2點原則上是利己,讓本身的服務可以擴大服務範圍;後面3點就是利他,讓第三方可以運用在Open API的基礎上,擴大提供加值的服務。

既然是利人利己的好事,那要如何開始呢,英國政府數位服務手冊關於API的指引部分提供10點指引參考[4],簡述如下:

1.建置API從本身使用做起(Build using your API):就是自己的API自己用的概念,不僅是驗證API的可用性,並且將API服務揭露於網路上。

2.使用標準規範(Use standards):將API視為網站的一部分,並提供一個超連結指向機器友善的格式。遵循網路的運作標準如HTTP和URL,並且使用已經建立好的認證網頁模式如OAuth 2

3.賦予每一資源可標記的URL(Give each resource a bookmarkable URL):提供語意式的URL,查詢字符串(query strings)只在無順序參數才使用,並且對不同細度的資源分別創建URL(如回傳會員名單/members.json、回傳會員詳細資訊/members.json?detail=full)。

4.使用HTTP通訊協定方法(Use HTTP methods):確保HTTP GET方法是安全而僅做為取得資料,而使用POST、PUT或DELETE方法是改變狀態的行為。另外,避免使用未被完善定義的方法如PATCH。

5.為顧客而做呈現(Representations are for the consumer):提供每個資源讓人類可讀的HTML內容,並且提供連結至替代的機器可讀內容的呈現,格式如JSON、JSONP、CSV、Atom、iCalendar、vCard、KML、m3u等。

6.使用命名原則以強化慣例(Use names to reinforce conventions)對於URL路徑的領域格式和路徑區段的命名在各API之間需一致建立慣例的命名原則可讓其他人容易遵循與預期範例可參考Microformats naming policy

7.API文件化(Document your API):建立網站透過連結(links)揭露資料,及透過HTML表單提供服務,以超文本的方式鼓勵探索與引導發現。提供API文件導引想要使用API的開發人員知道如何使用。

8.預設開放(Be open by default):降低其他人使用資料的障礙,如公開資料不需要註冊或API金鑰。如果內容需要認證程序,使用標準化的認證程序如基本認證或OAuth。API服務一定要透過HTTPS加密。

9.演練服務的演化(Practice service evolution):建立處理出現非預期內容的向前相容性及修正內容的向後相容性情境的處理機制。

10.消費與使用API(Consuming and using APIs):使用其他內部單位、政府部門或第三方的API,必須注意保持本身程式碼的乾淨與區別,以便於API更新版本時可以不必更動到本身的核心程式碼。

從以上的指引內容可以發現,實做Open API將主要牽涉到文件化、標準規範、管理等幾個層面。提供API就是希望能讓其他人來使用,如果其他人不知道API的內容,就必須要耗費時間摸索,甚至就會令人放棄而不想去用,所以首先先要讓人看得懂,文件化就是很重要的第一步驟。因此,軟體工程師JORDAN認為開發API準則的頭一項就是寫好API文件[5],提供TwilioDjangoMailChimp等做為參考的範本,內容大致包含整體說明、教學步驟、原始碼範例、相關參考資源等[6]

再者,API資源需要讓機器看得懂,這裡的用語只是與前面所提的讓人看得懂對應,其實機器處理普遍的情形是垃圾輸入、垃圾輸出(GIGO),所以,這裡強調的是盡可能注意使用共通標準規範的方式設計API,以便讓機器對機器溝通,如國發會「共通性資料存取應用程式介面規範[7]

最後,如前面開宗明義所揭示的,開放API就是要提供其他人來使用,因此,做好Open API的管理是很重要的事情,JORDAN也一再重申一個不良的設計、缺乏文件化、更動頻繁、遲遲未解決的bug等都讓API很難使用,這就是在API產品生命週期的過程之中,缺乏良善的管理方法。市面上許多公司提供API管理服務工具,VisionMobile網站介紹了13個工具,可讓API管理者依據需求來選擇,而管理上需要基本的需求如下幾項說明[8]

1.文件化:管理工具需提供簡便閱讀文件的方式,以及讓開發人員可以試用。

2.分析與統計:可以了解API是如何被使用與深入了解業務的運作。

3.佈署:能夠彈性且支援公有雲、私有雲、內部佈署實施或組合。

4.開發人員互動:與API消費者、開發者或夥伴互動是重要的。獲得容易進入開發者的入口可顯著地促進開發。

5.沙盒環境:此功能將增加API的價值與採用比率,比起能夠開發和測試API的程式碼更好。

6.流量管理與暫存能力。

7.安全性:API攜帶機敏的資料,必須能保護揭露的資訊。因此,此服務必須至少提供使用者和開發者能確認和存取管理。

8.獲利性:提供API獲利化的處理服務。

9.可用性:應提供可取得、延展與備用的服務,API環境可以變得嚴苛,服務應須能夠處理任何類型的錯誤、問題或暫時性的流量高峰。

10.支援舊有的系統。

[1] https://en.wikipedia.org/wiki/Open_API

[2]https://www.techopedia.com/2/31968/technology-trends/open-source/open-api-the-future-of-application-programming-interfaces

[3]http://18f.github.io/API-All-the-X/pages/introduction_to_APIs_in_government

[4]HTTPS://www.gov.uk/service-manual/making-software/apis.html

[5]https://www.toptal.com/api-developers/5-golden-rules-for-designing-a-great-web-api

[6]https://www.braintreepayments.com/blog/api-where-to-begin/

[7]https://www.facebook.com/notes/%E5%94%90%E9%B3%B3/112-%E8%B3%87%E8%A8%8A%E6%9C%8D%E5%8B%99%E7%94%A2%E6%A5%AD%E7%AD%96%E7%95%A5%E6%9C%83%E8%AD%B0-%E8%87%B4%E8%BE%AD/1409841909045025

[8]https://www.developereconomics.com/api-management-tools-how-to-find-the-one-for-you


作者:力信恩 中華民國資訊軟體協會

相關連結: