肆、指引準則

本指引之 API 設計主要依循共通性、輕便性及標準化準則。

● 共通性：

參採 Open API Initiative 組織之 OpenAPI Specification 標準，作為 API 說明文件之一致標準。

● 輕便性：

參考現階段及未來趨勢之 API 呼叫方式，採用 RESTful 風格 API。

● 標準化：

參考國際通用 W3C 相關標準(如 URI、HTTP 等)及 OData.org 相關規範訂定之。

一、詮釋資料集中至政府資料開放平臺

為實現共通性應用程式介面，API 開發應提供符合 OAS 標準之一致性描述方法，提供機器可讀之標準格式 API 說明文件。

提供 OAS 實際案例解析如附錄 1，並提供 OAS 標準之中文摘要譯本如附錄 2 供參。

（一）OAS 標準設計重點

● 符合 OAS 標準之 API 說明文件(以下簡稱 OAS 文件)原則上由單一檔案製成。

● OAS 文件需以 JSON 或 YAML 檔案格式呈現（API 本身的輸入和回傳值以及其他內容格式則未限制），並建議將 API 說明文件命名為 openapi.json 或 openapi.yaml。

● OAS 文件之基本資料類型是依據 JSON Schema Specification Wright Draft 00 支援的類型訂定。其架構基於根物件 OpenAPI Object 展開，物件具備各自的固定欄位(Fixed Fields)，各欄位之類型(Type)則須符合基本類別或物件定義。

參採 Open API Initiative 組織之 OpenAPI Specification 標準，作為 API 說明文件之一致標準。

欄位名稱 Field Name	類型 Type	描述 Description
openapi	string	必填，這字串必須載明該文件所使用的 OpenAPI Specification 版本。這個 openapi 欄位應該要讓使用者可藉由工具直譯其版本。該欄位與 API info 版本號無關。
info	Info Object	必填，提供這份 API 的詮釋資料。如有需要，這詮釋資料亦可由使用者所使用。
servers	[Server Object]	伺服器物件，可提供至目標伺服器之連結資訊。若未提供該欄位，或為空陣列，則伺服器欄位之預設 URL 將會是根目錄 "/"。
paths	Paths Object	必填，記載這份 API 的功能操作及可用路徑。
components	Components Object	用於記載保存於各種 schema 之元素。
security	[Security Requirement Object]	宣告其可跨用於整份 API 之安全機制。其清單內包含可供使用的 security requirement objects。僅需有一項滿足授權需求即可。可藉由個別操作覆蓋此定義。
tags	[Tag Object]	本標準於附加詮釋資料所使用的標籤清單。標籤順序可被分析工具所解析。並非所有 Operation Object 所使用的標籤都必須被宣告。未被宣告之標籤可被隨機地或邏輯性地組織起來。清單中每個標籤名稱都必須是獨一無二的。

（二）OAS 標準驗證方式

API 開發人員可透過 Open API Initiative 所提供之官方驗證工具，對 OAS 文件內容進行檢測，若檢測結果無錯誤訊息且其顯示內容符合機關之專案需求，可視為通過驗證。

二、RESTful API 語法規則

以政府資料開放平臺（data.gov.tw）為例，規劃 REST Web API，讓資料使用者可以 HTTP GET 方式，取得政府資料開放平臺之資料，API 呼叫回傳內容格式則以 JSON 為主，若 API 輸出內容格式為 JSON，則 HTTP header Content-Type 為 application/json。

服務路徑 URL 分為服務根網址(Service Root URL，簡稱 SRU)、資源路徑(Resource Path)和查詢選項(Query Options)：

● 服務根網址：

平臺上提供該類別應用服務之網址。

● 資源路徑：

接續於 SRU 後，以指定某一資源項目路徑名稱。

● 查詢選項：

接續於資源路徑後，針對某一應用服務，指定所欲取得資料之範圍或查詢之條件。

圖-1 URL 結構

依照上述 URL 結構定義，下圖以取得一資料集之資料資源內容 URL 為例。

圖-2 URL 結構範例說明

三、API 版本描述方式

因 API 規格或實作可能有版本之演進，故如有需要描述版本資訊應於服務根網址(Service Root URL)說明，如下圖。版本資訊格式建議使用 v1、v2、v3，不建議使用 v-1.1、v1.2、1.3。

圖-3 含有版本資訊 URL 結構範例說明

四、API Discovery

如機關所提供之 API 可供外界所查詢，建議可於首頁 html 文件或者是首頁的 Web 服務的 header 加入 API 鏈接關係，例如：

APIs.json 並非 OAS 標準的一部份，而是一個機器可讀的 sitemap 概念，可將該網站所有使用到的 API 進行列示。

五、Open API 設計建議

(一)建議高更新頻率資料或已有系統可即時產製之資料，可額外產製 Open API 供取用開放資料。

(二)Open API 設計須符合上述 RESTful API 語法規則，並提供符合 OAS3.0 含以上版本規範之機器可讀說明文件。

(三)依據「政府資料品質提升機制運作指引」，透過 Open API 取得之資料格式建議為 JSON、XML 格式，不建議回傳實體檔案或檔案下載連結。

(四)若需身分驗證、會員註冊、API KEY 限制之 API，需於 OAS 說明文件內註明驗證方式，若該 API 無提供驗證資訊、需額外申請、需付費使用之情況，皆不屬於 Open API 範圍。